Skip to content

Commit e1b5d75

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

File tree

1 file changed

+3
-3
lines changed

1 file changed

+3
-3
lines changed

README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -115,15 +115,14 @@ public interface Subscription {
115115
- The `Subscription.request` method SHOULD NOT synchronously perform heavy computations.
116116
- The `Subscription.cancel` method MUST assume that it will be invoked synchronously and SHOULD NOT synchronously perform heavy computations.
117117
118-
119-
118+
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.
120119
121120
### Asynchronous vs Synchronous Processing ###
122121
123122
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.
124123
125124
Take this example:
126-
125+
127126
```
128127
nioSelectorThreadOrigin map(f) filter(p) consumeTo(toNioSelectorOutput)
129128
```
@@ -157,6 +156,7 @@ All of these variants are "asynchronous streams". They all have their place and
157156

158157
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.
159158

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

161161

162162
### Subscriber controlled queue bounds ###

0 commit comments

Comments
 (0)