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
+5-6
Original file line number
Diff line number
Diff line change
@@ -79,8 +79,7 @@ followed by a possibly unbounded number of `onNext` signals (as requested by `Su
79
79
| <aname="term_non-obstructing">Non-obstructing</a> | Quality describing a method which is as quick to execute as possible—on the calling thread. This means, for example, avoids heavy computations and other things that would stall the caller´s thread of execution. |
80
80
| <aname="term_terminal_state">Terminal state</a> | For a Publisher: When `onComplete` or `onError` has been signalled. For a Subscriber: When an `onComplete` or `onError` has been received.|
81
81
| <aname="term_nop">NOP</a> | Execution that has no detectable effect to the calling thread, and can as such safely be called any number of times.|
82
-
| <aname="term_ext_sync">External synchronization</a> | Access coordination for thread safety purposes implemented outside of the constructs defined in this specification, using techniques such as, but not limited to, `atomics`, `monitors`, or `locks`. |
83
-
| <aname="term_thread-safe">Thread-safe</a> | Can be safely invoked synchronously, or asychronously, without requiring external synchronization to ensure program correctness. |
82
+
| <a name='term_serially">Serial(ly)</a> | In the context of a [Signal](#term_signal), non-overlapping. In the context of the JVM, calls to methods on an object are serial if and only if there is a happens-before relationship between those calls (implying also that the calls do not overlap). When the calls are performed asynchronously, coordination to establish the happens-before relationship is to be implemented using techniques such as, but not limited to, atomics, monitors, or locks. |
84
83
85
84
### SPECIFICATION
86
85
@@ -98,8 +97,8 @@ public interface Publisher<T> {
98
97
| [:bulb:](#1.1"1.1 explained") |*The intent of this rule is to make it clear that Publishers cannot signal more elements than Subscribers have requested. There’s an implicit, but important, consequence to this rule:Since demand can only be fulfilled after it has been received, there’s a happens-before relationship between requesting elements and receiving elements.*|
99
98
|<a name="1.2">2</a>|A `Publisher` MAY signal fewer `onNext` than requested and terminate the `Subscription` by calling `onComplete` or `onError`.|
100
99
| [:bulb:](#1.2"1.2 explained") |*The intent of this rule is to make it clear that a Publisher cannot guarantee that it will be able to produce the number of elements requested; it simply might not be able to produce them all; it may be in a failed state; it may be empty or otherwise already completed.*|
101
-
|<a name="1.3">3</a>| `onSubscribe`, `onNext`, `onError` and `onComplete` signaled to a `Subscriber` MUST be signaled in a [thread-safe](#term_thread-safe) manner—and if performed by multiple threads—use [external synchronization](#term_ext_sync).|
102
-
| [:bulb:](#1.3"1.3 explained") |*The intent of this rule is to make it clear that [external synchronization](#term_ext_sync) must be employedifthe Publisher intends to send signals from multiple/different threads.*|
100
+
|<a name="1.3">3</a>| `onSubscribe`, `onNext`, `onError` and `onComplete` signaled to a `Subscriber` MUST be signaled [serially](#term_serially).|
101
+
| [:bulb:](#1.3"1.3 explained") |*The intent of this rule is to permit the signalling of signals (including from multiple threads) if and onlyifa happens-before relation between each of the signals is established.*|
103
102
|<a name="1.4">4</a>|If a `Publisher` fails it MUST signal an `onError`.|
104
103
| [:bulb:](#1.4"1.4 explained") |*The intent of this rule is to make it clear that a Publisher is responsible for notifying its Subscribersif it detects that it cannot proceed—Subscribers must be given a chance to clean up resources or otherwise deal with the Publisher´s failures.*|
105
104
|<a name="1.5">5</a>|If a `Publisher` terminates successfully (finite stream) it MUST signal an `onComplete`.|
@@ -142,8 +141,8 @@ public interface Subscriber<T> {
142
141
| [:bulb:](#2.5"2.5 explained") |*The intent of this rule is to prevent that two, or more, separate Publishers from trying to interact with the same Subscriber. Enforcingthis rule means that resource leaks are prevented since extra Subscriptions will be cancelled. Failure to conform to this rule may lead to violations of Publisher rule 1, amongst others. Such violations can lead to hard-to-diagnose bugs.*|
143
142
|<a name="2.6">6</a>|A `Subscriber` MUST call `Subscription.cancel()` if the `Subscription` is no longer needed. |
144
143
| [:bulb:](#2.6"2.6 explained") |*The intent of this rule is to establish that Subscribers cannot just throwSubscriptions away when they are no longer needed, they have to call `cancel` so that resources held by that Subscription can be safely, and timely, reclaimed. An example of this would be a Subscriber which is only interested in a specific element, which would then cancel its Subscription to signal its completion to the Publisher.*|
145
-
|<a name="2.7">7</a>|A`Subscriber`MUST ensure that all calls on its `Subscription` take place from the same thread or provide for respective [external synchronization](#term_ext_sync).|
146
-
| [:bulb:](#2.7"2.7 explained") |*The intent of this rule is to establish that [external synchronization](#term_ext_sync) must be addedifa Subscriber will be using a Subscription concurrently by two or more threads.*|
144
+
|<a name="2.7">7</a>|ASubscriberMUST ensure that all calls on its Subscription's request and cancel methods are performed [serially](#term_serially). |
145
+
| [:bulb:](#2.7 "2.7 explained") | *The intent of this rule is to permit the calling of the request and cancel methods (including from multiple threads) if and only if a happens-before relation between each of the calls is established..* |
147
146
| <a name="2.8">8</a> | 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](#3.12)]. `Subscription.cancel()` does not guarantee to perform the underlying cleaning operations immediately. |
148
147
| [:bulb:](#2.8 "2.8 explained") | *The intent of this rule is to highlight that there may be a delay between calling `cancel` and the Publisher observing that cancellation.* |
149
148
| <a name="2.9">9</a> | A `Subscriber` MUST be prepared to receive an `onComplete` signal with or without a preceding `Subscription.request(long n)` call. |
0 commit comments