Договор об Observable

«Договор об Observable», который вы можете увидеть в различных местах в документации исходного кода и на страницах этого сайта, представляет собой попытку формального определения Observable, первоначально основанную на документе 2010 года Руководящие принципы разработки Rx от Microsoft, описывающем его реализацию Rx.NET ReactiveX.

На этой странице обобщен Договор об Observable.

Уведомления

Observable взаимодействует со своими наблюдателями с помощью следующих уведомлений:

OnNext: передает элемент, который издается Observable наблюдателю
OnCompleted: указывает, что Observable успешно завершился и больше не будет издавать элементы
OnError: указывает, что Observable завершился с указанным условием ошибки и больше не будет издавать элементы
OnSubscribe (необязательно): указывает, что Observable готов принять уведомления Request от наблюдателя (см. Управление потоком ниже)

Наблюдатель взаимодействует со своим Observable с помощью следующих уведомлений:

Subscribe: указывает, что наблюдатель готов получать уведомления от Observable
Unsubscribe: указывает, что наблюдатель больше не хочет получать уведомления от Observable
Request (необязательно): указывает, что наблюдатель хочет не более определенного количества дополнительных уведомлений OnNext от Observable (см. Управление потоком ниже)

Договор, регулирующий уведомления

Observable может сделать ноль или более уведомлений OnNext, каждое из которых представляет собой один изданный элемент, и после этих уведомлений об издании может последовать либо уведомление OnCompleted, либо OnError, но не оба. После выдачи уведомления OnCompleted или OnError оно больше не может выдавать какие-либо другие уведомления.

Observable может вообще не издавать элементов. Observable также может никогда не завершаться ни уведомлением OnCompleted, ни OnError. То есть, для Observable допустимо не издавать никаких уведомлений, издавать только уведомление OnCompleted или OnError или издавать только уведомления OnNext.

Observable должны издавать уведомления наблюдателям последовательно (а не параллельно). Они могут издавать эти уведомления из разных потоков, но между уведомлениями должна быть формальная связь happens-before.

Завершение Observable

Если Observable не выдал уведомления OnCompleted или OnError, наблюдатель может считать его по-прежнему активным (даже если он в настоящее время не издаёт элементы) и может издавать ему уведомления (например, уведомление Unsubscribe или Request). Когда Observable издаёт уведомление OnCompleted или OnError, Observable может освободить свои ресурсы и завершиться, и наблюдатели не должны пытаться далее с ним взаимодействовать.

Уведомление OnError должно содержать причину ошибки (то есть, недопустимо вызывать OnError со значением null).

Перед завершением Observable оно должно сначала выдать уведомление OnCompleted или OnError всем наблюдателям, подписанным на него.

Подписка и отписка

Observable может начать издавать уведомления наблюдателю сразу после того, как Observable получит от наблюдателя уведомление Subscribe.

Когда наблюдатель издаёт уведомление Unsubscribe Observable, Observable попытается прекратить выдачу уведомлений наблюдателю. Однако не гарантируется, что Observable не издаст никаких уведомлений наблюдателю после того, как наблюдатель отправит ему уведомление Unsubscribe.

Когда Observable издаёт уведомление OnError или OnComplete своим наблюдателям, это завершает подписку. Наблюдателям не нужно издавать уведомление Unsubscribe для завершения подписок, завершенных Observable таким образом.

Несколько наблюдателей

Если второй наблюдатель подписывается на Observable, который уже издаёт элементы первому наблюдателю, Observable решает, будет ли оно издавать одни и те же элементы каждому наблюдателю, или оно будет повторно издавать полную последовательность элементов с начала второму наблюдателю, или оно будет издавать совершенно другую последовательность элементов второму наблюдателю. Нет никакой общей гарантии, что два наблюдателя одного Observable увидят одну и ту же последовательность элементов.

Управление потоком

Управление потоком является необязательным; не все реализации ReactiveX включают управление потоком, и в тех, которые это делают, не все Observable или операторы поддерживают управление потоком. Observable может реализовать управление потоком, если обнаружит, что его наблюдатель реализует уведомления Request и понимает уведомления OnSubscribe.

Если Observable реализует управление потоком, и его наблюдатель использует управление потоком, Observable не начнёт издавать элементы наблюдателю сразу после подписки. Вместо этого он выпустит уведомление OnSubscribe наблюдателю.

В любое время после получения уведомления OnSubscribe наблюдатель может выдать уведомление Request Observable, на которое он подписан. Это уведомление запрашивает определённое количество элементов. Observable реагирует на такой Request, издав не более элементов, чем запросил наблюдатель. Однако Observable может, кроме того, выдать уведомление OnCompleted или OnError, и даже может выдать такое уведомление до того, как наблюдатель запросит какие-либо элементы.

Observable, не реализующий управление потоком, должен реагировать на уведомление Request от наблюдателя, выдав уведомление OnError, указывающее, что управление потоком не поддерживается.

Запросы кумулятивны. Например, если наблюдатель издаёт три уведомления Request Observable, на 3, 5 и 10 элементов соответственно, этот Observable может издать до 18 элементов наблюдателю, независимо от того, когда эти уведомления Request поступили относительно того, когда Observable издал элементы в ответ.

Если Observable производит больше элементов, чем запросил наблюдатель, Observable решает, будет ли оно отбрасывать избыточные элементы, хранить их для выпуска в более позднее время или использовать другую стратегию для обработки переполнения.