Skip to content

Latest commit

 

History

History
149 lines (86 loc) · 5.43 KB

DESIGN.md

File metadata and controls

149 lines (86 loc) · 5.43 KB

RxJava v2 Design

Terminology, principles, contracts, and other aspects of the design of RxJava v2.

Terminology & Definitions

Hot

When used to refer to a data source (such as an Observable), it means it does not have side-effects when subscribed to.

For example, an Observable of mouse events. Subscribing to that Observable does not cause the mouse events, but starts receiving them.

(Note: Yes, there are some side-effects of adding a listener, but they are inconsequential as far as the 'hot' usage is concerned).

Cold

When used to refer to a data source (such as an Observable), it means it has side-effects when subscribed to.

For example, an Observable of data from a remote API (such as an RPC call). Each time that Observable is subscribed to causes a new network call to occur.

Reactive

Producer is in charge. Consumer has to do whatever it needs to keep up.

Interactive

Consumer is in charge. Producer has to do whatever it needs to keep up.

Push

Producer emits when it wishes to. Related to "reactive". Callbacks are an instance of push.

Pull

Consumer requests data when it wishes to. Related to "interactive". An Iterable is an instance of pull.

Async Pull

Consumer requests data when it wishes, and the data is then pushed when the producer wishes to. The Reactive Streams Publisher is an instance of "async pull", as is the 'AsyncEnumerable' in .Net.

RxJava & Related Types

Observable

Stream that supports async and synchronous push. It does not support interactive flow control (request(n)).

Usable for:

  • hot and cold sources
  • sync or async
  • push
  • 0, 1, many or infinite items

Flow control support:

  • buffering, sampling, throttling, windowing, dropping, etc
  • temporal and count-based strategies
Flowable

Stream that supports async and synchronous push and pull. It supports interactive flow control (request(n)).

Usable for:

  • hot and cold sources
  • sync or async
  • push
  • pull
  • 0, 1, many or infinite items

Flow control support:

  • buffering, sampling, throttling, windowing, dropping, etc
  • temporal and count-based strategies
  • request(n) consumer demand signal
    • for pull-based sources, this allows batched "async pull"
    • for push-based sources, this allows backpressure signals to conditionally apply strategies (i.e. drop, buffer, sample, fail, etc)
Observer

Consumer of events without flow control.

Publisher

Reactive Streams producer of data

Subscriber

Reactive Streams consumer of data.

Subscription

Reactive Streams state of subscription supporting flow control and cancellation.

Processor

Reactive Streams operator for defining behavior between Publisher and Subscriber. It must obey the contracts of Publisher and Subscriber, meaning it is sequential, serialized, and must obey request(n) flow control.

Subject

A "hot", push-based data source that allows a producer to emit events to it and consumers to subscribe to events in a multicast manner. It is "hot" because consumers subscribing to it does not cause side-effects, or affect the data flow in any way. It is push-based and reactive because the producer is fully in charge.

Relation to Reactive Streams

  • It can not implement Reactive Streams Publisher unless it is created with a default flow control strategy.
  • It can not implement Processor since a Processor must compose request(n) which can not be done with multicasting or pure push.

Flow control support:

  • buffering, sampling, throttling, windowing, dropping, etc
  • temporal and count-based strategies
  • It does not support pull-based consumer-driven flow control.
Disposable

A type representing work that can be cancelled or disposed.

Behavior

Creation

Creation of a stream falls into the following use cases, all of which should be catered to in API design.

  • async, hot, push (ie. system or user events)
  • async, cold, push (ie. events resulting from remote system via network connection)
  • sync, cold, pull (ie. iterable, file, range)
  • async, cold, pull (ie. RPC/REST network call, cross-thread queue draining)

Unknown:

  • hot, pull (what is an example of this?)

Flow control support:

  • If request(n) behavior is supported in the stream implementation, then:
  • pull-based creation must support request(n) semantics
  • push-based creation must provide a default onBackpressure strategy
  • If request(n) behavior is not supported in the stream implementation, then:
  • push-based creation can push without consideration of a backpressure strategy
  • pull-based creation should be discouraged
Destruction

A producer can terminate a stream by emitting onComplete or onError. A consumer can terminate a stream by calling cancel.

Any resource cleanup of the source or operators must account for any of these three termination events. In other words, if an operator needs cleanup, then it should register the cleanup callback with cancel, onError and onComplete.

The final subscribe will not invoke cancel after receiving an onComplete or onError.