You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+57-49
Original file line number
Diff line number
Diff line change
@@ -81,26 +81,28 @@ public interface Publisher<T> {
81
81
}
82
82
````
83
83
84
-
1.The number of `onNext` signaled by a `Publisher` to a `Subscriber` MUSTNOT exceed the cumulative demand that has been signaled via that `Subscriber`’s `Subscription`.
85
-
2.A `Publisher` MAY signal less `onNext` than requested and terminate the `Subscription` by calling `onComplete` or `onError`.
86
-
3.Events signaled to a `Subscriber` MUST be signaled sequentially (no concurrent notifications).
87
-
4.If a `Publisher` fails it MUST signal an `onError`.
88
-
5.If a `Publisher` terminates successfully (finite stream) it MUST signal an `onComplete`.
89
-
6.If a Publisher signals either `onError` or `onComplete` on a `Subscriber`, that `Subscriber`’s `Subscription` MUST be considered canceled.
90
-
7.Once a terminal state has been signaled (`onError`, `onComplete`) it is REQUIRED that no further signals occur.
91
-
8.Upon receiving a `Subscription.cancel` request it SHOULD, as soon as it can, stop signaling its `Subscriber`.
92
-
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`.
93
-
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]_
94
-
11. The `Subscriber.onSubscribe` method on a given `Subscriber` instance MUST NOT be called more than once (based on object equality).
95
-
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.
96
-
13. A `Publisher` MAY support multi-subscribe and choose whether each `Subscription` is unicast or multicast.
97
-
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]_
98
-
15. A `Publisher` in `completed` state MUST NOT call `Subscriber.onSubscribe` and MUST signal an `Subscriber.onComplete` on the given `Subscriber`
99
-
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`
100
-
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.
101
-
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]_
102
-
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.
103
-
20. A `Publisher` MUST start producing with the oldest element still available for a new `Subscription`.
|1|The number of `onNext` signaled by a `Publisher` to a `Subscriber` MUSTNOT exceed the cumulative demand that has been |
87
+
|2|A `Publisher` MAY signal less `onNext` than requested and terminate the `Subscription` by calling `onComplete` or `onError` |
88
+
|3|Events signaled to a `Subscriber` MUST be signaled sequentially (no concurrent notifications) |
89
+
|4|If a `Publisher` fails it MUST signal an `onError` |
90
+
|5|If a `Publisher` terminates successfully (finite stream) it MUST signal an `onComplete` |
91
+
|6|If a Publisher signals either `onError` or `onComplete` on a `Subscriber`, that `Subscriber`’s `Subscription` MUST be considered canceled |
92
+
|7|Once a terminal state has been signaled (`onError`, `onComplete`) it is REQUIRED that no further signals occur |
93
+
|8|Upon receiving a `Subscription.cancel` request it SHOULD, as soon as it can, stop signaling its `Subscriber` |
94
+
|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` |
95
+
| 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]_ |
96
+
| 11 | The `Subscriber.onSubscribe` method on a given `Subscriber` instance MUST NOT be called more than once (based on object equality) |
97
+
| 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 |
98
+
| 13 | A `Publisher` MAY support multi-subscribe and choose whether each `Subscription` is unicast or multicast |
99
+
| 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]_ |
100
+
| 15 | A `Publisher` in `completed` state MUST NOT call `Subscriber.onSubscribe` and MUST signal an `Subscriber.onComplete` on the given `Subscriber` |
101
+
| 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` |
102
+
| 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 |
103
+
| 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]_ |
104
+
| 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 |
105
+
| 20 | A `Publisher` MUST start producing with the oldest element still available for a new `Subscription` |
@@ -113,17 +115,19 @@ public interface Subscriber<T> {
113
115
}
114
116
````
115
117
116
-
1. A `Subscriber` MUST signal demand via `Subscription.request(int n)` to receive onNext signals.
117
-
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.
118
-
3.A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUSTNOT call any methods on the `Subscription`, the `Publisher` or any other `Publishers` or `Subscribers`. [UnderDiscussion]
119
-
4.A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST consider the Subscription cancelled after having received the signal.
120
-
5.A `Subscriber` MUSTNOT 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).
121
-
6.A `Subscriber` MUST call `Subscription.cancel()` if it is no longer valid to the `Publisher` without the `Publisher` having signaled `onError` or `onComplete`.
122
-
7.A `Subscriber` MUST ensure that all calls on its `Subscription` take place from the same thread or provide for respective external synchronization.
123
-
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.
124
-
9.A `Subscriber` MUST be prepared to receive an `onComplete` signal with or without a preceding `Subscription.request(int n)` call.
125
-
10.A `Subscriber` MUST be prepared to receive an `onError` signal with or without a preceding `Subscription.request(int n)` call.
126
-
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.
| 1 | A `Subscriber` MUST signal demand via `Subscription.request(int n)` to receive onNext signals |
121
+
| 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 |
122
+
|3|A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUSTNOT call any methods on the `Subscription`, the `Publisher` or any other `Publishers` or `Subscribers`. [UnderDiscussion] |
123
+
|4|A `Subscriber.onComplete()` and `Subscriber.onError(Throwable t)` MUST consider the Subscription cancelled after having received the signal |
124
+
|5|A `Subscriber` MUSTNOT 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) |
125
+
|6|A `Subscriber` MUST call `Subscription.cancel()` if it is no longer valid to the `Publisher` without the `Publisher` having signaled `onError` or `onComplete` |
126
+
|7|A `Subscriber` MUST ensure that all calls on its `Subscription` take place from the same thread or provide for respective external synchronization |
127
+
|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 |
128
+
|9|A `Subscriber` MUST be prepared to receive an `onComplete` signal with or without a preceding `Subscription.request(int n)` call |
129
+
|10|A `Subscriber` MUST be prepared to receive an `onError` signal with or without a preceding `Subscription.request(int n)` call |
130
+
|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 |
@@ -134,20 +138,22 @@ public interface Subscription {
134
138
}
135
139
````
136
140
137
-
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].
138
-
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.
139
-
3.The `Subscription.request` method MUST assume that it will be invoked synchronously and MUSTNOT allow unbounded recursion such as `Subscriber.onNext` -> `Subscription.request` -> `Subscriber.onNext`. _[UnderDiscussion]_
140
-
4.The `Subscription.request` method SHOULDNOT synchronously perform heavy computations.
141
-
5.The `Subscription.cancel` method MUST assume that it will be invoked synchronously and SHOULDNOT synchronously perform heavy computations.
142
-
6.After the `Subscription` is cancelled, additional `Subscription.request(int n)` MUST be NOPs.
143
-
7.After the `Subscription` is cancelled, additional `Subscription.cancel()` MUST be NOPs.
144
-
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.
145
-
9.While the `Subscription` is not cancelled, `Subscription.request(int n)` MUSTthrow 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.
146
-
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.
147
-
11.While the `Subscription` is not cancelled, `Subscription.request(int n)` MAY synchronously call `onComplete` or `onError` on this (or other) subscriber(s).
148
-
12.While the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually cease to call any methods on the corresponding subscriber.
149
-
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.
150
-
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"SubscribersSHOULD prevent automatic shutdown if required.
|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] |
144
+
|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 |
145
+
|3|The `Subscription.request` method MUST assume that it will be invoked synchronously and MUSTNOT allow unbounded recursion such as `Subscriber.onNext` -> `Subscription.request` -> `Subscriber.onNext`. _[UnderDiscussion]_ |
146
+
|4|The `Subscription.request` method SHOULDNOT synchronously perform heavy computations |
147
+
|5|The `Subscription.cancel` method MUST assume that it will be invoked synchronously and SHOULDNOT synchronously perform heavy computations |
148
+
|6|After the `Subscription` is cancelled, additional `Subscription.request(int n)` MUST be NOPs|
149
+
|7|After the `Subscription` is cancelled, additional `Subscription.cancel()` MUST be NOPs|
150
+
|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 |
151
+
|9|While the `Subscription` is not cancelled, `Subscription.request(int n)` MUSTthrow 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 |
152
+
|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 |
153
+
|11|While the `Subscription` is not cancelled, `Subscription.request(int n)` MAY synchronously call `onComplete` or `onError` on this (or other) subscriber(s) |
154
+
|12|While the `Subscription` is not cancelled, `Subscription.cancel()` the `Publisher` MUST eventually cease to call any methods on the corresponding subscriber |
155
+
|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 |
156
+
|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"SubscribersSHOULD prevent automatic shutdown if required |
151
157
152
158
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.
0 commit comments