Skip to content

Commit b7a95e6

Browse files
committed
document rationale for void return of subscribe()
fixes reactive-streams#43
1 parent ae4b75a commit b7a95e6

File tree

1 file changed

+5
-1
lines changed

1 file changed

+5
-1
lines changed

README.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ Subscribers that do not currently have an active subscription may subscribe to a
7575
At any time the Publisher may signal that it is not able to provide more elements. This is done by invoking onComplete on its subscribers.
7676

7777
> For example a Publisher representing a strict collection signals completion to its subscriber after it provided all the elements. Now a later subscriber might still receive the whole collection before receiving onComplete.
78+
79+
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.
7880

7981
### API components ###
8082

@@ -90,7 +92,9 @@ In addition there is one method each on Producer and Consumer to obtain a refere
9092

9193
The Reactive Streams SPI prescribes that all processing of elements (onNext) or termination signals (onError, onComplete) happens outside of the execution stack of the Publisher. This is achieved by scheduling the processing to run asynchronously, possibly on a different thread. The Subscriber should make sure to minimize the amount of processing steps used to initiate this process, meaning that all its SPI-mandated methods shall return as quickly as possible.
9294

93-
In contrast to communicating back-pressure by blocking the publisher, a non-blocking solution needs to communicate demand through a dedicated control channel. This channel is provided by the Subscription: the subscriber controls the maximum amount of future elements it is willing receive by sending explicit demand tokens (by calling requestMore(int)).
95+
In contrast to communicating back-pressure by blocking the publisher, a non-blocking solution needs to communicate demand through a dedicated control channel. This channel is provided by the Subscription: the subscriber controls the maximum amount of future elements it is willing receive by sending explicit demand tokens (by calling requestMore(int)).
96+
97+
In order to allow fully asynchronous implementations of all participating SPI elements—`Publisher`/`Subscription`/`Subscriber`—all methods defined by these interfaces return `void`.
9498

9599
#### Relationship to synchronous stream-processing ####
96100

0 commit comments

Comments
 (0)