创建一个Observable需要遵守的规定。

本文为翻译。

The Observable Contract

The Observable Contract (Observable契约)

“The Observable Contract,” which you may see referenced in various places in source documentation and in the pages on this site, is an attempt at a formal definition of an Observable, based originally on the 2010 document Rx Design Guidelines from Microsoft that described itsRx.NETimplementation of ReactiveX.

关于Observable Contract你可能在某些版本的源码或者本站的一些网页中看到过,该契约 尝试去规范一个Observable的定义,其中基本的要点来源于2010微软描述它的Rx.NET库的文档。


This page summarizes The Observable Contract.

该页总结了Observable Contract

Notifications

An Observable communicates with its observers with the following notifications:

一个Observable通过以下的通知来跟它的订阅者来通讯。

OnNext

conveys an item that is emitted by the Observable to the observer

发送一个item给它的订阅者

OnCompleted

indicates that the Observable has completed successfully and that it will be emitting no further items

表明一个Observable成功的结束了,它将不会再发送任何数据。

OnError

indicates that the Observable has terminated with a specified error condition and that it will be emitting no further items

表明一个Observable被一个特定的错误给终止了,终止后它不会再发送任何数据。

OnSubscribe (optional)

indicates that the Observable is ready to accept Request notifications from the observer (see Backpressure below)

表明Observable准备接受订阅者的Request通知(参考下面的背压描述)。


An observer communicates with its Observable by means of the following notifications:

一个订阅者通过下面几种方式来跟它的Observable来交流

Subscribe

indicates that the observer is ready to receive notifications from the Observable

表明该订阅者准备好接收来自Observable的通知。

Unsubscribe

indicates that the observer no longer wants to receive notifications from the Observable

表明该订阅者不想再接收observable的通知。

Request (optional--可选的)

indicates that the observer wants no more than a particular number of additional OnNext notifications from the Observable (see Backpressure below)

表明该订阅者想要不超过指定数量的onNext通知(主要用于背压)。

The Contract Governing Notifications

An Observable may make zero or more OnNext notifications, each representing a single emitted item, and it may then follow those emission notifications by either an OnCompleted or an OnError notification, but not both. Upon issuing an OnCompleted or OnError notification, it may not thereafter issue any further notifications.

一个Observable可能发送0个或者多个OnNext通知,每个OnNext代表一个发送的数据项, 它可能随后会发送一个OnCompleted或者一个OnError通知,但不是两个都会发。(我们在使用OnCreate创建一个Observable,最后要么发送OnCompleted要么发送一个OnError),在发送了OnCompleted或者OnError之后不应该再送任何的通知。

An Observable may emit no items at all. An Observable may also never terminate with either an OnCompleted or an OnError notification. That is to say that it is proper for an Observable to issue no notifications, to issue only an OnCompleted or an OnError notification, or to issue only OnNext notifications.

一个Observable可能不会发送一个数据项。也可能不会通过发送OnCompleted或者一个OnError来终止。也就是说一个只发送OnNext通知,或者只发送OnCompleted、OnError通知的Observable是可以的。

Observables must issue notifications to observers serially (not in parallel). They may issue these notifications from different threads, but there must be a formal happens-before relationship between the notifications.

Observables必须以连续(而不是并行)的方式发送通知。可以在不同的线程中发送通知,但是必须有形式上happens-before关系,我的理解是线程的启动顺序是连续的。


Observable Termination

If an Observable has not issued an OnCompleted or OnError notification, an observer may consider it to be still active (even if it is not currently emitting items) and may issue it notifications (such as an Unsubscribe or Request notification). When an Observable does issue an OnCompleted or OnError notification, the Observable may release its resources and terminate, and its observers should not attempt to communicate with it any further.

如果一个Observable没有发送一个OnCompleted或者一个OnError通知,那么它的订阅者 会该Observable是活动的(尽管它当前没有发送items),所以订阅者Observer还是会向Observable发送通知(例如Unsubscribe通知或者Request通知)。当一个Observable确实发送了一个OnCompleted或者一个OnError通知,那么该Observable可能会释放自己的资源并且终止,那么它的订阅者们(Observers)不应该再去尝试与该Observable连接。

An OnError notification must contain the cause of the error (that is to say, it is invalid to call OnError with a null value).Before an Observable terminates it must first issue either an OnCompleted or OnError notification to all of the observers that are subscribed to it.

一个OnError通知必须包含引起该错误的原因,也就是说一个包含null的OnError通知是无效的。一个Observable在终止之前必须发送一个OnCompleted或者一个OnError通知来告诉它的订阅者observers。


Subscribing and Unsubscribing

An Observable may begin issuing notifications to an observer immediately after the Observable receives a Subscribe notification from the observer.

一个Observable被一个订阅者observer订阅的时候可能会马上发送一个通知。

When an observer issues an Unsubscribe notification to an Observable, the Observable will attempt to stop issuing notifications to the observer. It is not guaranteed, however, that the Observable will issue no notifications to the observer after an observer issues it an Unsubscribe notification.

当一个订阅者发送一个Unsubscribe通知给一个Observable的时候,这个Observable将会尝试停止发送通知给这个订阅者observer,但并不保障一定会这样,不管怎样,在一个订阅者发送它的Unsubscribe通知后,这个Observable将不会发送通知给这个订阅者。

When an Observable issues an OnError or OnComplete notification to its observers, this ends the subscription. Observers do not need to issue an Unsubscribe notification to end subscriptions that are ended by the Observable in this way.当一个Observable发送一个OnError或者一个OnComplete通知给他订阅者们,这会结束这个subscription。那么订阅者也就不需要发送一个Unsubscribe通知去结束这个subscription了。


Multiple Observers

If a second observer subscribes to an Observable that is already emitting items to a first observer, it is up to the Observable whether it will thenceforth emit the same items to each observer, or whether it will replay the complete sequence of items from the beginning to the second observer, or whether it will emit a wholly different sequence of items to the second observer. There is no general guarantee that two observers of the same Observable will see the same sequence of items.

如果第二个订阅者去订阅同一个Observable,此时这个Observable已经发送过一些items给第一个订阅者了。那么是把剩余的items发送给第二个订阅者,还是重复的把前面已经发过的items和剩余的一起发送给第二个订阅者,亦或者是发送与第一个订阅者完全不同items,这都是由Observable来决定。也不存在明确的规定一定要发送相同的items给不同订阅者。


Backpressure

Backpressure is optional; not all ReactiveX implementations include backpressure, and in those that do, not all Observables or operators honor backpressure. An Observable may implement backpressure if it detects that its observer implements Request notifications and understands OnSubscribe notifications.

背压是可选的,并不是一定要求实现背压。也就是说并不是所有的Observable或者操作符都有背压功能。如果一个Observable能够处理来自订阅者发送的Request通知,那么该Observable可能实现了背压功能。

If an Observable implements backpressure and its observer employs backpressure, the Observable will not begin to emit items to the observer immediately upon subscription. Instead, it will issue an OnSubscribe notification to the observer.

如果一个Observable实现了背压功能,当订阅者订阅它的时候并不会马上发送items给这个订阅者,而是发送一个OnSubscribe通知。

At any time after it receives an OnSubscribe notification, an observer may issue a Request notification to the Observable it has subscribed to. This notification requests a particular number of items. The Observable responds to such a Request by emitting no more items to the observer than the number of items the observer requests. However the Observable may, in addition, issue an OnCompleted or OnError notification, and it may even issue such a notification before the observer requests any items at all.

在一个订阅者(Observer)订阅了Observable之后的任何时候,该订阅者如果发送了一个Request通知(Request通知表示订阅者想要接收指定数量的items)给Observable,Observable将会发送不超过指定数量的items给订阅者来响应该Request通知。然而,Observable这时候有可能会额外的发送一个OnCompleted或者一个OnError通知。甚至在订阅者请求任何items通知之前(也就是Request通知)该Observable发送OnCompleted或者OnError通知也是有可能的。

An Observable that does not implement backpressure should respond to a Request notification from an observer by issuing an OnError notification that indicates that backpressure is not supported.

如果一个Observable没有实现背压,那么当接收到订阅者的Request通知时应该发送一个OnError通知来响应该Request通知,以此来表明该Observable不支持背压。

Requests are cumulative. For example, if an observer issues three Request notifications to an Observable, for 3, 5, and 10 items respectively, that Observable may emit as many as 18 items to the observer, no matter when those Request notifications arrived relative to when the Observable emitted items in response.

Request通知是可以累积的。例如,一个订阅者向它的Observable发送了3次Request通知,这3次通知分别请求3,5,10个items。那么它的Observable可能会发送18个items给该订阅者。这跟Request到达时Observable已经发送多少items没有关系。比如第三个Request到达时,Observable才一共发送了7个items,并不是表明Observable只需要发满10个。

If the Observable produces more items than the observer requests, it is up to the Observable whether it will discard the excess items, store them to emit at a later time, or use some other strategy to deal with the overflow.

如果一个Observable生产了多过订阅者要求的数量的items,那么多余的items是被丢弃或者存储下来用来以后发送,亦或者使用其他策略来处理都是由Observable来决定的。

推荐阅读更多精彩内容