https://github.com/ReactiveCocoa/ReactiveObjC/blob/master/Documentation/DesignGuidelines.md#process-only-as-much-of-a-stream-as-needed
Design Guidelines
This document contains guidelines for projects that want to make use of ReactiveCocoa. The content here is heavily inspired by the Rx Design Guidelines.
This document assumes basic familiarity with the features of ReactiveCocoa. The Framework Overview is a better resource for getting up to speed on the functionality provided by RAC.
The RACSequence contract
RACSequence is a pull-driven stream. Sequences behave similarly to built-in collections, but with a few unique twists.
Evaluation occurs lazily by default
1:Sequences are evaluated lazily by default. For example, in this sequence:
… no string appending is actually performed until the values of the sequence are needed
2:This generally avoids performing unnecessary work (since values that are never used are never calculated), but means that sequence processing should be limited only to what's actually needed.
3:Once evaluated, the values in a sequence are memoized and do not need to be recalculated. Accessing sequence.headmultiple times will only do the work of one string concatenation.
4:If lazy evaluation is undesirable – for instance, because limiting memory usage is more important than avoiding unnecessary work – the eagerSequence property can be used to force a sequence (and any sequences derived from it afterward) to evaluate eagerly.
Evaluation blocks the caller
1:Regardless of whether a sequence is lazy or eager, evaluation of any part of a sequence will block the calling thread until completed.This is necessary because values must be synchronously retrieved from a sequence.
2:If evaluating a sequence is expensive enough that it might block the thread for a significant amount of time, consider creating a signal with -signalWithScheduler: and using that instead.
Side effects occur only once
1:When the block passed to a sequence operator involves side effects, it is important to realize that those side effects will only occur once per value – namely, when the value is evaluated:
The RACSignal contract
1:RACSignal is a push-driven stream with a focus on asynchronous event delivery through subscriptions.
Signal events are serialized
1:A signal may choose to deliver its events on any thread. Consecutive events are even allowed to arrive on different threads or schedulers, unless explicitly delivered onto a particular scheduler.
2:However, RAC guarantees that no two signal events will ever arrive concurrently.
3:While an event is being processed, no other events will be delivered.
4:The senders of any other events will be forced to wait until the current event has been handled.
5:Most notably, this means that the blocks passed to -subscribeNext:error:completed: do not need to be synchronized with respect to each other, because they will never be invoked simultaneously.
Subscription will always occur on a scheduler
1:To ensure consistent behavior for the +createSignal: and -subscribe: methods, each RACSignal subscription is guaranteed to take place on a valid RACScheduler.
2:If the subscriber's thread already has a +currentScheduler, scheduling takes place immediately; otherwise, scheduling occurs as soon as possible on a background scheduler.
3:Note that the main thread is always associated with the +mainThreadScheduler, so subscription will always be immediate there.
Errors are propagated immediately
1:In RAC, error events have exception semantics. When an error is sent on a signal, it will be immediately forwarded to all dependent signals, causing the entire chain to terminate.
2:Operators whose primary purpose is to change error-handling behavior – like -catch:, -catchTo:, or -materialize – are obviously not subject to this rule.
Side effects occur for each subscription
1:Each new subscription to a RACSignal will trigger its side effects.
2: This means that any side effects will happen as many times as subscriptions to the signal itself.
3:Side effects are repeated for each subscription. The same applies to stream and signal operators:
4:To suppress this behavior and have multiple subscriptions to a signal execute its side effects only once, a signal can bemulticasted.
5:Side effects can be insidious and produce problems that are difficult to diagnose. For this reason it is suggested to make side effects explicit when possible.
Subscriptions are automatically disposed upon completion or error
1:When a subscriber is sent a completed or error event, the associated subscription will automatically be disposed. This behavior usually eliminates the need to manually dispose of subscriptions.
2:See the Memory Management document for more information about signal lifetime.
Disposal cancels in-progress work and cleans up resources
1:When a subscription is disposed, manually or automatically, any in-progress or outstanding work associated with that subscription is gracefully cancelled as soon as possible, and any resources associated with the subscription are cleaned up.
2:Disposing of the subscription to a signal representing a file upload, for example, would cancel any in-flight network request, and free the file data from memory.
