Skip to content

2.x Design: Creation/Destruction #3350

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Sep 17, 2015
Merged

2.x Design: Creation/Destruction #3350

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,4 +74,35 @@ It is "hot" because consumers subscribing to it does not cause side-effects, or

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)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some network messages have to get off the OS buffer into application memory or result in data loss. There could be variable amount of work (ranging from trivial to laborious) involved to parse from bytes to application domain which means that they should be called "cold" to cover the extreme cases however because of the potentially lossy nature of OS buffers it may be required to subscribe and parse it. Should we differentiate between persistent (non-lossy) network and (volatile) network buffering?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand your point. Rx does not involve itself in network behaviors. What are you suggesting should be changed in the text?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that events resulting from remote system via network connection should be considered hot. Then that leaves the question of... what async push events are actually cold?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The confusion is cleared up. My comment here had more to do with the choice of whether a network connection is wrapped in an Observable (hot) or a Flowable (cold). As most network connections are potentially lossy (TCP and UDP overflowing the OS buffer for instance) the choice would be made according to the developers confidence in the ability to consume data fast enough to prevent loss (Observable -> Flowable with a back pressure strategy). Anyhow, I'll defer my comments from making any change here in this PR to later clarifications of wording.

- sync, cold, pull (ie. iterable, file, range)
- async, cold, pull (ie. RPC/REST network call, cross-thread queue draining)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RPC/REST network call

sounds like "initiating network requests" as opposed to "accepting network requests" which would be the async, cold, push pattern above. This has the option of canceling or optionally not parsing the response while the other push case is bound to the usage contract of not dropping/losing the request and producing a response.


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`.