Skip to content

Commit

Permalink
document rationale for void return of subscribe()
Browse files Browse the repository at this point in the history
fixes #43
  • Loading branch information
rkuhn committed May 20, 2014
1 parent e01ebd4 commit e1b5d75
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,15 +115,14 @@ public interface Subscription {
- The `Subscription.request` method SHOULD NOT synchronously perform heavy computations.
- The `Subscription.cancel` method MUST assume that it will be invoked synchronously and SHOULD NOT synchronously perform heavy computations.
A `Subscription` is shared by exactly one `Publisher` and one `Subscriber` for the purpose of mediating the data exchange between this pair. This is the reason why the `subscribe()` method does not return the created `Subscription`, but instead returns `void`; the `Subscription` is only passed to the `Subscriber` via the `onSubscribe` callback.
### Asynchronous vs Synchronous Processing ###
The Reactive Streams API prescribes that all processing of elements (`onNext`) or termination signals (`onError`, `onComplete`) MUST NOT *block* the `Publisher`. However, each of the `on*` handlers can process the events synchronously or asynchronously.
Take this example:
```
nioSelectorThreadOrigin map(f) filter(p) consumeTo(toNioSelectorOutput)
```
Expand Down Expand Up @@ -157,6 +156,7 @@ All of these variants are "asynchronous streams". They all have their place and

The Reactive Streams contract allows implementations the flexibility to manage resources and scheduling and mix asynchronous and synchronous processing within the bounds of a non-blocking, asynchronous, push-based stream.

In order to allow fully asynchronous implementations of all participating SPI elements—`Publisher`/`Subscription`/`Subscriber`—all methods defined by these interfaces return `void`.


### Subscriber controlled queue bounds ###
Expand Down

0 comments on commit e1b5d75

Please sign in to comment.