Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Observable contract #3132

Closed
davidmoten opened this issue Aug 6, 2015 · 10 comments
Closed

Documentation: Observable contract #3132

davidmoten opened this issue Aug 6, 2015 · 10 comments
Assignees

Comments

@davidmoten
Copy link
Collaborator

The Observable contract is mentioned in many places in ReactiveX documentation, rxjava wiki and in Subject javadocs but without links or clarification to what it is and where to find it (I think!).

I believe the contract is defined in 'Rx Design Guidelines.pdf' section 4 from Microsoft but at the moment this fact is not easily discoverable in the documentation.

My first idea is to create a page in ReactiveX documentation say called Observable contract which itself references the pdf for the moment and then all links would be to that Observable contract page.

@DavidMGross your thoughts?

@akarnokd
Copy link
Member

akarnokd commented Aug 6, 2015

I think it should be part of the Observable javadoc and link to it at the relevant places via hash-anchor.

@davidmoten
Copy link
Collaborator Author

That sounds good to me, and I suppose a copy of it needs to go in the more generic ReactiveX doco. By it you mean the details of the contract extracted from the pdf?

@DavidMGross DavidMGross self-assigned this Aug 6, 2015
@DavidMGross
Copy link
Collaborator

I'll see if I can work up a summary page about the Observable contract for the website. Are there important elements of this contract that are not reflected in the 2010 Microsoft design guidelines? For example, should there be any discussion of backpressure (e.g. what an Observable should do if it does not support backpressure and an observer attempts to apply it)?

@DavidMGross
Copy link
Collaborator

Here's a first attempt: http://reactivex.io/documentation/contract.html

@DavidMGross
Copy link
Collaborator

Should this page also perhaps discuss the correct behavior of an Observable if an observer does not implement onNext, onError, and/or onCompleted, or of any of those methods throws an exception?

@davidmoten
Copy link
Collaborator Author

Thanks @DavidMGross

Observables must send notifications serially, in a single thread, and not in parallel.

Single thread is not required, as long as the emissions happen serially (which basically means not in parallel). You could say

Observables must send notifications serially (not in parallel). The notifications may be sent from different threads but there must be a formal happens-before relationship between the notifications.

@akarnokd will be good for cleaning up this statement!

@davidmoten
Copy link
Collaborator Author

https://github.com/reactive-streams/reactive-streams-jvm/#1-publisher-code covers most of it and includes backpressure. It could be translated into RxJava speak and bulked up a bit (the reactive-streams-jvm specification itself is going to be bulked up with comments when people get round to it).

@DavidMGross
Copy link
Collaborator

Please see ReactiveX/reactivex.github.io#133 for my latest draft of the contract, including a discussion of backpressure. I'd appreciate your comments and corrections.

@DavidMGross
Copy link
Collaborator

Thanks, Dave; that's very useful.

On Thu, Aug 6, 2015 at 8:46 PM, Dave Moten [email protected] wrote:

https://github.com/reactive-streams/reactive-streams-jvm/#1-publisher-code
covers most of it and includes backpressure. It could be translated into
RxJava speak and bulked up a bit (the reactive-streams-jvm specification
itself is going to be bulked up with comments when people get round to it).


Reply to this email directly or view it on GitHub
#3132 (comment).

David M. Gross
PLP Consulting

@DavidMGross
Copy link
Collaborator

I think I've got this pretty well nailed down. Let me know if you have any comments, corrections, or additions.

http://reactivex.io/documentation/contract.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants