Documentation: Observable contract

[davidmoten]

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]

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

[davidmoten]

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]

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]

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

[DavidMGross]

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]

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]

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]

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]

Thanks, Dave; that's very useful.

On Thu, Aug 6, 2015 at 8:46 PM, Dave Moten notifications@github.com 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]

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