Skip to content

Commit 8efd004

Browse files
DavidMGrossDavidMGross
committed
add more to "contract" page incl. back pressure section
1 parent acc0068 commit 8efd004

File tree

1 file changed

+71
-9
lines changed

1 file changed

+71
-9
lines changed

‎documentation/contract.markdown

Lines changed: 71 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,16 @@ id: contract
66

77
<h1>The Observable Contract</h1>
88
<p>
9-
&ldquo;The Observable Contract,&rdquo; which you may see referred to in various places in source documentation
10-
and in the pages on this site, is an attempt at a formal definition of an Observable, based originally on the
11-
2010 document <a href="https://go.microsoft.com/fwlink/?LinkID=205219"><cite>Rx Design Guidelines</cite></a>
12-
from Microsoft that described its Rx.NET implementation of ReactiveX.
9+
“The Observable Contract,” which you may see referenced in various places in source documentation and in the
10+
pages on this site, is an attempt at a formal definition of an Observable, based originally on the 2010
11+
document <a href="https://go.microsoft.com/fwlink/?LinkID=205219"><cite>Rx Design Guidelines</cite></a> from
12+
Microsoft that described its Rx.NET implementation of ReactiveX.
1313
</p><p>
1414
This page summarizes The Observable Contract.
1515
</p>
16-
<h2>Notifications from an Observable</h2>
16+
<h2>Notifications</h2>
1717
<p>
18-
An Observable communicates with its observers by means of <i>notifications</i>. There are three varieties of
19-
notification:
18+
An Observable communicates with its observers with the following <i>notifications</i>:
2019
</p>
2120
<dl>
2221
<dt>OnNext</dt>
@@ -25,6 +24,19 @@ id: contract
2524
<dd>indicates that the Observable has completed successfully and that it will be emitting no further items</dd>
2625
<dt>OnError</dt>
2726
<dd>indicates that the Observable has terminated with a specified error condition and that it will be emitting no further items</dd>
27+
<dt>OnSubscribe (optional)</dt>
28+
<dd>indicates that the Observable is ready to accept Request notifications from the observer (see <i>Backpressure</i> below)</dd>
29+
</dl>
30+
<p>
31+
An observer communicates with its Observable by means of the following notifications:
32+
</p>
33+
<dl>
34+
<dt>Subscribe</dt>
35+
<dd>indicates that the observer is ready to receive notifications from the Observable</dd>
36+
<dt>Unsubscribe</dt>
37+
<dd>indicates that the observer no longer wants to receive notifications from the Observable</dd>
38+
<dt>Request (optional)</dt>
39+
<dd>indicates that the observer wants no more than a particular number of additional OnNext notifications from the Observable (see <i>Backpressure</i> below)</dd>
2840
</dl>
2941
<h2>The Contract Governing Notifications</h2>
3042
<p>
@@ -40,12 +52,62 @@ id: contract
4052
notifications from different threads, but there must be a formal <i>happens-before</i> relationship between the
4153
notifications.
4254
</p>
55+
<h2>Observable Termination</h2>
56+
<p>
57+
If an Observable has not issued an OnCompleted or OnError notification, an observer may consider it to be still
58+
active (even if it is not currently emitting items) and may issue it notifications (such as an Unsubscribe
59+
or Request notification). When an Observable does issue an OnCompleted or OnError notification, the Observable
60+
may release its resources and terminate, and its observers should not attempt to communicate with it any
61+
further.
62+
</p><p>
63+
Before an Observable releases its resources and terminates it must first issue either an OnCompleted or OnError
64+
notification to all of the observers that are subscribed to it.
65+
</p>
4366
<h2>Subscribing and Unsubscribing</h2>
4467
<p>
4568
An Observable may begin issuing notifications to an observer immediately after the Observable receives a
4669
Subscribe notification from the observer.
4770
</p><p>
48-
When an observer sends an Unsubscribe notification to an Observable, the Observable will attempt to stop
71+
When an observer issues an Unsubscribe notification to an Observable, the Observable will attempt to stop
4972
issuing notifications to the observer. It is not guaranteed, however, that the Observable will issue
50-
<em>no</em> notifications to the observer after an observer sends it an Unsubscribe notification.
73+
<em>no</em> notifications to the observer after an observer issues it an Unsubscribe notification.
74+
</p><p>
75+
When an Observable issues an OnError or OnComplete notification to its observers, this ends the subscription.
76+
Observers do not need to issue an Unsubscribe notification to end subscriptions that are ended by the Observable
77+
in this way.
78+
</p>
79+
<h2>Multiple Observers</h2>
80+
<p>
81+
If a second observer subscribes to an Observable that is already emitting items to a first observer, it is up
82+
to the Observable whether it will thenceforth emit the same items to each observer, or whether it will replay
83+
the complete sequence of items from the beginning to the second observer, or whether it will emit a wholly
84+
different sequence of items to the second observer. There is no general guarantee that two observers of the
85+
same Observable will see the same sequence of items.
86+
</p>
87+
<h2>Backpressure</h2>
88+
<p>
89+
Backpressure is optional; not all ReactiveX implementations include backpressure, and in those that do, not all
90+
Observables or operators honor backpressure. An Observable <em>may</em> implement backpressure if it detects
91+
that its observer implements <i>Request</i> notifications and understands <i>OnSubscribe</i> notifications.
92+
</p><p>
93+
If an Observable implements backpressure and its observer employs backpressure, the Observable will not begin
94+
to emit items to the observer immediately upon subscription. Instead, it will issue an OnSubscribe notification
95+
to the observer.
96+
</p><p>
97+
At any time after it receives an OnSubscribe notification, an observer may issue a Request notification to the
98+
Observable it has subscribed to. This notification requests a particular number of items. The Observable
99+
responds to such a Request by emitting no more items to the observer than the number of items the observer
100+
requests. However the Observable may, in addition, issue an OnCompleted or OnError notification, and it may
101+
even issue such a notification before the observer requests any items at all.
102+
</p><p>
103+
An Observable that does not implement backpressure should respond to a Request notification from an observer
104+
by issuing an OnError notification that indicates that backpressure is not supported.
105+
</p><p>
106+
Requests are cumulative. For example, if an observer issues three Request notifications to an Observable, for
107+
3, 5, and 10 items respectively, that Observable may emit as many as 18 items to the observer, no matter when
108+
those Request notifications arrived relative to when the Observable emitted items in response.
109+
</p><p>
110+
If the Observable produces more items than the observer requests, it is up to the Observable whether it will
111+
discard the excess items, store them to emit at a later time, or use some other strategy to deal with the
112+
overflow.
51113
</p>

0 commit comments

Comments
 (0)