Skip to content

Commit 29804c5

Browse files
author
Stephane Maldini
committed
Fix after second round comments
1 parent c800041 commit 29804c5

File tree

1 file changed

+41
-37
lines changed

1 file changed

+41
-37
lines changed

‎README.md

+41-37
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ onError | (onSubscribe onNext* (onError | onComplete)?)
5959

6060
NOTE: The specifications below use binding words in CAPLOCKS from https://www.ietf.org/rfc/rfc2119.txt
6161

62+
NOTE: The terms emit, signal or send are interchangeable. The specifications below will use `signal`.
63+
64+
NOTE: The terms `synchronously` or `synchronous` refer to executing in the calling `Thread`.
65+
6266
### SPECIFICATION
6367

6468
#### 1. Publisher ([Code](https://github.com/reactive-streams/reactive-streams/blob/master/api/src/main/java/org/reactivestreams/Publisher.java))
@@ -69,26 +73,26 @@ public interface Publisher<T> {
6973
}
7074
````
7175

72-
1. The number of `onNext` events emitted by a `Publisher` to a `Subscriber` MUST NOT exceed the cumulative demand that has been signaled via that `Subscriber`’s `Subscription`.
73-
2. A `Publisher` MAY send less events than requested and terminate the `Subscription` by calling `onComplete` or `onError`.
74-
3. Events sent to a `Subscriber` MUST be sent sequentially (no concurrent notifications).
75-
4. If a `Publisher` fails it MUST emit an `onError`.
76-
5. If a `Publisher` terminates successfully (finite stream) it MUST emit an `onComplete`.
76+
1. The number of `onNext` signaled by a `Publisher` to a `Subscriber` MUST NOT exceed the cumulative demand that has been signaled via that `Subscriber`’s `Subscription`.
77+
2. A `Publisher` MAY signal less `onNext` than requested and terminate the `Subscription` by calling `onComplete` or `onError`.
78+
3. Events signaled to a `Subscriber` MUST be signaled sequentially (no concurrent notifications).
79+
4. If a `Publisher` fails it MUST signal an `onError`.
80+
5. If a `Publisher` terminates successfully (finite stream) it MUST signal an `onComplete`.
7781
6. If a Publisher signals either `onError` or `onComplete` on a `Subscriber`, that `Subscriber`’s `Subscription` MUST be considered canceled.
78-
7. Once a terminal state has been signaled (`onError`, `onComplete`) it is REQUIRED that no further events can be sent.
79-
8. Upon receiving a `Subscription.cancel` request it SHOULD, as soon as it can, stop sending events.
80-
9. `Subscription`'s which have been canceled SHOULD NOT receive subsequent `onError` or `onComplete` events, but implementations will not be able to strictly guarantee this in all cases due to the intrinsic race condition between actions taken concurrently by `Publisher` and `Subscriber`.
81-
10. A `Publisher` SHOULD NOT throw an `Exception`. The only legal way to signal failure (or reject a `Subscription`) is via the `Subscriber.onError` method.
82-
11. The `Subscriber.onSubscribe` method on a given `Subscriber` instance MUST NOT be called more than once.
83-
12. The `Publisher.subscribe` method MAY be called as many times as wanted but MUST be with a different (based on object equality) Subscriber each time. It MUST reject the Subscription with a `java.lang.IllegalStateException` if the same Subscriber already has an active `Subscription` with this `Publisher`. The cause message SHOULD include a reference to this rule and/or quote the full rule.
82+
7. Once a terminal state has been signaled (`onError`, `onComplete`) it is REQUIRED that no further signals occur.
83+
8. Upon receiving a `Subscription.cancel` request it SHOULD, as soon as it can, stop signaling its `Subscriber`.
84+
9. `Subscription`'s which have been canceled SHOULD NOT receive subsequent `onError` or `onComplete` signals, but implementations will not be able to strictly guarantee this in all cases due to the intrinsic race condition between actions taken concurrently by `Publisher` and `Subscriber`.
85+
10. A `Publisher` SHOULD NOT throw an `Exception`. The only legal way to signal failure (or reject a `Subscription`) is via the `Subscriber.onError` method. [Under Discussion]
86+
11. The `Subscriber.onSubscribe` method on a given `Subscriber` instance MUST NOT be called more than once (based on object equality).
87+
12. The `Publisher.subscribe` method MAY be called as many times as wanted but MUST be with a different Subscriber each time [see 1.11]. It MUST reject the Subscription with a `java.lang.IllegalStateException` if the same Subscriber already has an active `Subscription` with this `Publisher`. The cause message MUST include a reference to this rule and/or quote the full rule.
8488
13. A `Publisher` MAY support multi-subscribe and choose whether each `Subscription` is unicast or multicast.
85-
14. A `Publisher` MAY reject calls to its `subscribe` method if it is unable or unwilling to serve them (e.g. because it is overwhelmed or bounded by a finite number of underlying resources, etc...). If rejecting it MUST do this by calling `onError` on the `Subscriber` passed to `Publisher.subscribe` instead of calling `onSubscribe`".
86-
15. A `Publisher` in `completed` state MUST NOT call `Subscriber.onSubscribe` and MUST emit an `Subscriber.onComplete` on the given `Subscriber`
87-
16. A `Publisher` in `error` state MUST NOT call `Subscriber.onSubscribe` and MUST emit an `Subscriber.onError` with the error cause on the given `Subscriber`
88-
17. A `Publisher` in `shut-down` state MUST NOT call `Subscriber.onSubscribe` and MUST emit an `Subscriber.onError` with `java.lang.IllegalStateException` on the given `Subscriber`. The cause message SHOULD include a reference to this rule and/or quote the full rule.
89-
18. A `Publisher` MUST support a pending element count up to 2^63-1 (java.lang.Long.MAX_VALUE) and provide for overflow protection.
89+
14. A `Publisher` MAY reject calls to its `subscribe` method if it is unable or unwilling to serve them (e.g. because it is overwhelmed or bounded by a finite number of underlying resources, etc...). If rejecting it MUST do this by calling `onError` on the `Subscriber` passed to `Publisher.subscribe` instead of calling `onSubscribe`". [Under Discussion]
90+
15. A `Publisher` in `completed` state MUST NOT call `Subscriber.onSubscribe` and MUST signal an `Subscriber.onComplete` on the given `Subscriber`
91+
16. A `Publisher` in `error` state MUST NOT call `Subscriber.onSubscribe` and MUST signal an `Subscriber.onError` with the error cause on the given `Subscriber`
92+
17. A `Publisher` in `shut-down` state MUST NOT call `Subscriber.onSubscribe` and MUST signal an `Subscriber.onError` with `java.lang.IllegalStateException` on the given `Subscriber`. The cause message MUST include a reference to this rule and/or quote the full rule.
93+
18. A `Publisher` MUST support a pending element count up to 2^63-1 (java.lang.Long.MAX_VALUE) and provide for overflow protection. [Under Discussion]
9094
19. A `Publisher` MUST produce the same elements in the same sequence for all its subscribers. Producing the stream elements at (temporarily) differing rates to different subscribers is allowed.
91-
20. A `Publisher` MUST start producing with the oldest element still available for a new subscriber.
95+
20. A `Publisher` MUST start producing with the oldest element still available for a new `Subscription`.
9296
9397
#### 2. Subscriber ([Code](https://github.com/reactive-streams/reactive-streams/blob/master/api/src/main/java/org/reactivestreams/Subscriber.java))
9498
@@ -101,17 +105,17 @@ public interface Subscriber<T> {
101105
}
102106
````
103107
104-
1. A `Subscriber` MUST signal demand via `Subscription.request(int n)` to receive onNext notifications.
105-
2. A `Subscriber` MAY behave synchronously or asynchronously but SHOULD NOT synchronously perform heavy computations in its methods (`onNext`, `onError`, `onComplete`, `onSubscribe`).
106-
3. A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST NOT call any methods on the `Subscription`, the `Publisher` or any other `Publishers` or `Subscribers`.
107-
4. A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST consider the Subscription cancelled after having received the event
108-
5. A `Subscriber` MUST NOT accept an `onSubscribe` event if it already has an active Subscription. What exactly "not accepting" means is left to the implementation but should include behavior that makes the user aware of the usage error (e.g. by logging, throwing an exception or similar).
109-
6. A `Subscriber` MUST call `Subscription.cancel()` if it is no longer valid to the `Publisher` without the `Publisher` having signalled `onError` or `onComplete`.
108+
1. A `Subscriber` MUST signal demand via `Subscription.request(int n)` to receive onNext signals.
109+
2. If a `Subscriber` suspects that its processing of events will negatively impact its `Publisher`'s responsivity, it is RECOMMENDED that it asynchronously dispatches its signals.
110+
3. A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST NOT call any methods on the `Subscription`, the `Publisher` or any other `Publishers` or `Subscribers`. [Under Discussion]
111+
4. A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST consider the Subscription cancelled after having received the signal.
112+
5. A `Subscriber` MUST NOT accept an `onSubscribe` signal if it already has an active `Subscription`. What exactly "not accepting" means is left to the implementation but should include behavior that makes the user aware of the usage error (e.g. by logging, throwing an exception or similar).
113+
6. A `Subscriber` MUST call `Subscription.cancel()` if it is no longer valid to the `Publisher` without the `Publisher` having signaled `onError` or `onComplete`.
110114
7. A `Subscriber` MUST ensure that all calls on its `Subscription` take place from the same thread or provide for respective external synchronization.
111-
8. A `Subscriber` MUST be prepared to receive one or more `onNext` events after having called `Subscription.cancel()` if there are still requested elements pending.
112-
9. A `Subscriber` MUST be prepared to receive an `onComplete` event with or without a preceding `Subscription.request(int n)` call.
113-
10. A `Subscriber` MUST be prepared to receive an `onError` event with or without a preceding `Subscription.request(int n)` call.
114-
11. A `Subscriber` MUST make sure that all calls on its `onXXX` methods happen-before the processing of the respective events. I.e. the Subscriber must take care of properly publishing the event to its processing logic.
115+
8. A `Subscriber` MUST be prepared to receive one or more `onNext` signals after having called `Subscription.cancel()` if there are still requested elements pending [see 3.12]. `Subscription.cancel()` does not guarantee to perform the underlying cleaning operations immediately.
116+
9. A `Subscriber` MUST be prepared to receive an `onComplete` signal with or without a preceding `Subscription.request(int n)` call.
117+
10. A `Subscriber` MUST be prepared to receive an `onError` signal with or without a preceding `Subscription.request(int n)` call.
118+
11. A `Subscriber` MUST make sure that all calls on its `onXXX` methods happen-before the processing of the respective signals. I.e. the Subscriber must take care of properly publishing the signal to its processing logic.
115119

116120
#### 3. Subscription ([Code](https://github.com/reactive-streams/reactive-streams/blob/master/api/src/main/java/org/reactivestreams/Subscription.java))
117121

@@ -122,20 +126,20 @@ public interface Subscription {
122126
}
123127
````
124128

125-
1. A `Subscription` can be used once-and-only-once to represent a subscription by a `Subscriber` to a `Publisher`.
129+
1. A `Subscription.request` and `Subscription.cancel` MUST not be called outside its `Subscriber` context. A `Subscription` represents the unique relationship between a `Subscriber` and a `Publisher` [see 1.11].
126130
2. Calls from a `Subscriber` to `Subscription.request(int n)` can be made directly since it is the responsibility of `Subscription` to handle async dispatching.
127131
3. The `Subscription.request` method MUST assume that it will be invoked synchronously and MUST NOT allow unbounded recursion such as `Subscriber.onNext` -> `Subscription.request` -> `Subscriber.onNext`.
128132
4. The `Subscription.request` method SHOULD NOT synchronously perform heavy computations.
129133
5. The `Subscription.cancel` method MUST assume that it will be invoked synchronously and SHOULD NOT synchronously perform heavy computations.
130134
6. After the `Subscription` is cancelled, additional `Subscription.request(int n)` MUST be NOPs.
131135
7. After the `Subscription` is cancelled, additional `Subscription.cancel()` MUST be NOPs.
132-
8. When the `Subscription` is not cancelled, `Subscription.request(int n)` MUST register the given number of additional elements to be produced to the respective subscriber.
133-
9. When the `Subscription` is not cancelled, `Subscription.request(int n)` MUST throw a `java.lang.IllegalArgumentException` if the argument is <= 0. The cause message SHOULD include a reference to this rule and/or quote the full rule.
134-
10. When the `Subscription` is not cancelled, `Subscription.request(int n)` COULD synchronously call `onNext` on this (or other) subscriber(s) if and only if the next element is already available.
135-
11. When the `Subscription` is not cancelled, `Subscription.request(int n)` COULD synchronously call `onComplete` or `onError` on this (or other) subscriber(s).
136-
12. When the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually cease to call any methods on the corresponding subscriber.
137-
13. When the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually drop any references to the corresponding subscriber. Re-subscribing with the same `Subscriber` instance is discouraged, but this specification does not mandate that it is disallowed since that would mean having to store previously canceled subscriptions indefinitely.
138-
14. When the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST transition to a `shut-down` state [see 1.17] if the given `Subscription` is the last downstream `Subscription`. Explicitly adding "keep-alive" Subscribers SHOULD prevent automatic shutdown if required.
136+
8. While the `Subscription` is not cancelled, `Subscription.request(int n)` MUST register the given number of additional elements to be produced to the respective subscriber.
137+
9. While the `Subscription` is not cancelled, `Subscription.request(int n)` MUST throw a `java.lang.IllegalArgumentException` if the argument is <= 0. The cause message MUST include a reference to this rule and/or quote the full rule.
138+
10. While the `Subscription` is not cancelled, `Subscription.request(int n)` MAY synchronously call `onNext` on this (or other) subscriber(s) if and only if the next element is already available.
139+
11. While the `Subscription` is not cancelled, `Subscription.request(int n)` MAY synchronously call `onComplete` or `onError` on this (or other) subscriber(s).
140+
12. While the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually cease to call any methods on the corresponding subscriber.
141+
13. While the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually drop any references to the corresponding subscriber. Re-subscribing with the same `Subscriber` object is discouraged [see 1.11], but this specification does not mandate that it is disallowed since that would mean having to store previously canceled subscriptions indefinitely.
142+
14. While the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST transition to a `shut-down` state [see 1.17] if the given `Subscription` is the last downstream `Subscription`. Explicitly adding "keep-alive" Subscribers SHOULD prevent automatic shutdown if required.
139143

140144
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.
141145

@@ -148,7 +152,7 @@ public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {
148152

149153
1. A `Processor` represents a processing stage—which is both a `Subscriber` and a `Publisher` and MUST obey the contracts of both.
150154
2. A `Processor` MUST cancel its upstream Subscription if its last downstream Subscription has been cancelled.
151-
3. A `Processor` MUST immediately pass on `onError` events received from its upstream to its downstream.
155+
3. A `Processor` MUST immediately pass on `onError` signals received from its upstream to its downstream.
152156
4. A `Processor` MUST be prepared to receive incoming elements from its upstream even if a downstream subscriber has not requested anything yet.
153157

154158
### Asynchronous vs Synchronous Processing ###
@@ -212,4 +216,4 @@ Subscribers signaling a demand for one element after the reception of an element
212216
213217
## Legal
214218
215-
This project is a collaboration between engineers from Netflix, Twitter, RedHat, Pivotal, Typesafe and many others. The code is offered to the Public Domain in order to allow free use by interested parties who want to create compatible implementations. For details see `COPYING`.
219+
This project is a collaboration between engineers from Netflix, Pivotal, RedHat, Twitter, Typesafe and many others. The code is offered to the Public Domain in order to allow free use by interested parties who want to create compatible implementations. For details see `COPYING`.

0 commit comments

Comments
 (0)