From e1b5d7509f519bde8de58ad6b887e91b4458cccb Mon Sep 17 00:00:00 2001 From: Roland Kuhn Date: Mon, 12 May 2014 23:02:52 +0200 Subject: [PATCH] document rationale for void return of subscribe() fixes #43 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7051cec6..60d2ebec 100644 --- a/README.md +++ b/README.md @@ -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) ``` @@ -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 ###