onecable_ios_user/Carthage/Checkouts/ReactiveCocoa/Documentation/DesignGuidelines.md

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 main types and concepts provided by RAC.

The Event contract

1. Nexts provide values or indicate the occurrence of events
2. Failures behave like exceptions and propagate immediately
3. Completion indicates success
4. Interruption cancels outstanding work and usually propagates immediately
5. Events are serial
6. Events cannot be sent recursively
7. Events are sent synchronously by default

The Signal contract

1. Signals start work when instantiated
2. Observing a signal does not have side effects
3. All observers of a signal see the same events in the same order
4. A signal is retained until the underlying observer is released
5. Terminating events dispose of signal resources

The SignalProducer contract

1. Signal producers start work on demand by creating signals
2. Each produced signal may send different events at different times
3. Signal operators can be lifted to apply to signal producers
4. Disposing of a produced signal will interrupt it

Best practices

1. Process only as many values as needed
2. Observe events on a known scheduler
3. Switch schedulers in as few places as possible
4. Capture side effects within signal producers
5. Share the side effects of a signal producer by sharing one produced signal
6. Prefer managing lifetime with operators over explicit disposal

Implementing new operators

1. Prefer writing operators that apply to both signals and producers
2. Compose existing operators when possible
3. Forward failure and interruption events as soon as possible
4. Switch over Event values
5. Avoid introducing concurrency
6. Avoid blocking in operators

The Event contract

Events are fundamental to ReactiveCocoa. Signals and signal producers both send events, and may be collectively called “event streams.”

Event streams must conform to the following grammar:

Next* (Interrupted | Failed | Completed)?

This states that an event stream consists of:

1. Any number of Next events
2. Optionally followed by one terminating event, which is any of Interrupted, Failed, or Completed

After a terminating event, no other events will be received.

Nexts provide values or indicate the occurrence of events

Next events contain a payload known as the “value.” Only Next events are said to have a value. Since an event stream can contain any number of Nexts, there are few restrictions on what those values can mean or be used for, except that they must be of the same type.

As an example, the value might represent an element from a collection, or a progress update about some long-running operation. The value of a Next event might even represent nothing at all—for example, it’s common to use a value type of () to indicate that something happened, without being more specific about what that something was.

Most of the event stream operators act upon Next events, as they represent the “meaningful data” of a signal or producer.

Failures behave like exceptions and propagate immediately

Failed events indicate that something went wrong, and contain a concrete error that indicates what happened. Failures are fatal, and propagate as quickly as possible to the consumer for handling.

Failures also behave like exceptions, in that they “skip” operators, terminating them along the way. In other words, most operators immediately stop doing work when a failure is received, and then propagate the failure onward. This even applies to time-shifted operators, like delay—which, despite its name, will forward any failures immediately.

Consequently, failures should only be used to represent “abnormal” termination. If it is important to let operators (or consumers) finish their work, a Next event describing the result might be more appropriate.

If an event stream can never fail, it should be parameterized with the special NoError type, which statically guarantees that a Failed event cannot be sent upon the stream.

Completion indicates success

An event stream sends Completed when the operation has completed successfully, or to indicate that the stream has terminated normally.

Many operators manipulate the Completed event to shorten or extend the lifetime of an event stream.

For example, take will complete after the specified number of values have been received, thereby terminating the stream early. On the other hand, most operators that accept multiple signals or producers will wait until all of them have completed before forwarding a Completed event, since a successful outcome will usually depend on all the inputs.

Interruption cancels outstanding work and usually propagates immediately

An Interrupted event is sent when an event stream should cancel processing. Interruption is somewhere between success and failure—the operation was not successful, because it did not get to finish, but it didn’t necessarily “fail” either.

Most operators will propagate interruption immediately, but there are some exceptions. For example, the flattening operators will ignore Interrupted events that occur on the inner producers, since the cancellation of an inner operation should not necessarily cancel the larger unit of work.

RAC will automatically send an Interrupted event upon disposal, but it can also be sent manually if necessary. Additionally, custom operators must make sure to forward interruption events to the observer.

Events are serial

RAC guarantees that all events upon a stream will arrive serially. In other words, it’s impossible for the observer of a signal or producer to receive multiple Events concurrently, even if the events are sent on multiple threads simultaneously.

This simplifies operator implementations and observers.

Events cannot be sent recursively

Just like RAC guarantees that events will not be received concurrently, it also guarantees that they won’t be received recursively. As a consequence, operators and observers do not need to be reentrant.

If an event is sent upon a signal from a thread that is already processing a previous event from that signal, deadlock will result. This is because recursive signals are usually programmer error, and the determinacy of a deadlock is preferable to nondeterministic race conditions.

When a recursive signal is explicitly desired, the recursive event should be time-shifted, with an operator like delay, to ensure that it isn’t sent from an already-running event handler.

Events are sent synchronously by default

RAC does not implicitly introduce concurrency or asynchrony. Operators that accept a scheduler may, but they must be explicitly invoked by the consumer of the framework.

A “vanilla” signal or producer will send all of its events synchronously by default, meaning that the observer will be synchronously invoked for each event as it is sent, and that the underlying work will not resume until the event handler finishes.

This is similar to how NSNotificationCenter or UIControl events are distributed.

The Signal contract

A signal is an “always on” stream that obeys the Event contract.

Signal is a reference type, because each signal has identity—in other words, each signal has its own lifetime, and may eventually terminate. Once terminated, a signal cannot be restarted.

Signals start work when instantiated

Signal.init immediately executes the generator closure that is passed to it. This means that side effects may occur even before the initializer returns.

It is also possible to send events before the initializer returns. However, since it is impossible for any observers to be attached at this point, any events sent this way cannot be received.

Observing a signal does not have side effects

The work associated with a Signal does not start or stop when observers are added or removed, so the observe method (or the cancellation thereof) never has side effects.

A signal’s side effects can only be stopped through a terminating event.

All observers of a signal see the same events in the same order

Because observation does not have side effects, a Signal never customizes events for different observers. When an event is sent upon a signal, it will be synchronously distributed to all observers that are attached at that time, much like how NSNotificationCenter sends notifications.

In other words, there are not different event “timelines” per observer. All observers effectively see the same stream of events.

There is one exception to this rule: adding an observer to a signal after it has already terminated will result in exactly one Interrupted event sent to that specific observer.

A signal is retained until the underlying observer is released

Even if the caller does not maintain a reference to the Signal:

• A signal created with Signal.init is kept alive until the generator closure releases the observer argument.
• A signal created with Signal.pipe is kept alive until the returned observer is released.

This ensures that signals associated with long-running work do not deallocate prematurely.

Note that it is possible to release a signal before a terminating event has been sent upon it. This should usually be avoided, as it can result in resource leaks, but is sometimes useful to disable termination.

Terminating events dispose of signal resources

When a terminating event is sent along a Signal, all observers will be released, and any resources being used to generate events should be disposed of.

The easiest way to ensure proper resource cleanup is to return a disposable from the generator closure, which will be disposed of when termination occurs. The disposable should be responsible for releasing memory, closing file handles, canceling network requests, or anything else that may have been associated with the work being performed.

The SignalProducer contract

A signal producer is like a “recipe” for creating signals. Signal producers do not do anything by themselves—work begins only when a signal is produced.

Since a signal producer is just a declaration of how to create signals, it is a value type, and has no memory management to speak of.

Signal producers start work on demand by creating signals

The start and startWithSignal methods each produce a Signal (implicitly and explicitly, respectively). After instantiating the signal, the closure that was passed to SignalProducer.init will be executed, to start the flow of events after any observers have been attached.

Although the producer itself is not really responsible for the execution of work, it’s common to speak of “starting” and “canceling” a producer. These terms refer to producing a Signal that will start work, and disposing of that signal to stop work.

A producer can be started any number of times (including zero), and the work associated with it will execute exactly that many times as well.

Each produced signal may send different events at different times

Because signal producers start work on demand, there may be different observers associated with each execution, and those observers may see completely different event timelines.

In other words, events are generated from scratch for each time the producer is started, and can be completely different (or in a completely different order) from other times the producer is started.

Nonetheless, each execution of a signal producer will follow the Event contract.

Signal operators can be lifted to apply to signal producers

Due to the relationship between signals and signal producers, it is possible to automatically promote any operators over one or more Signals to apply to the same number of SignalProducers instead, using the lift method.

lift will apply the behavior of the specified operator to each Signal that is created when the signal producer is started.

Disposing of a produced signal will interrupt it

When a producer is started using the start or startWithSignal methods, a Disposable is automatically created and passed back.

Disposing of this object will interrupt the produced Signal, thereby canceling outstanding work and sending an Interrupted event to all observers, and will also dispose of everything added to the CompositeDisposable in SignalProducer.init.

Note that disposing of one produced Signal will not affect other signals created by the same SignalProducer.

Best practices

The following recommendations are intended to help keep RAC-based code predictable, understandable, and performant.

They are, however, only guidelines. Use best judgement when determining whether to apply the recommendations here to a given piece of code.

Process only as many values as needed

Keeping an event stream alive longer than necessary can waste CPU and memory, as unnecessary work is performed for results that will never be used.

If only a certain number of values or certain number of time is required from a signal or producer, operators like take or takeUntil can be used to automatically complete the stream once a certain condition is fulfilled.

The benefit is exponential, too, as this will terminate dependent operators sooner, potentially saving a significant amount of work.

Observe events on a known scheduler

When receiving a signal or producer from unknown code, it can be difficult to know which thread events will arrive upon. Although events are guaranteed to be serial, sometimes stronger guarantees are needed, like when performing UI updates (which must occur on the main thread).

Whenever such a guarantee is important, the observeOn operator should be used to force events to be received upon a specific scheduler.

Switch schedulers in as few places as possible

Notwithstanding the above, events should only be delivered to a specific scheduler when absolutely necessary. Switching schedulers can introduce unnecessary delays and cause an increase in CPU load.

Generally, observeOn should only be used right before observing the signal, starting the producer, or binding to a property. This ensures that events arrive on the expected scheduler, without introducing multiple thread hops before their arrival.

Capture side effects within signal producers

Because signal producers start work on demand, any functions or methods that return a signal producer should make sure that side effects are captured within the producer itself, instead of being part of the function or method call.

For example, a function like this:

func search(text: String) -> SignalProducer<Result, NetworkError>

… should not immediately start a search.

Instead, the returned producer should execute the search once for every time that it is started. This also means that if the producer is never started, a search will never have to be performed either.

Share the side effects of a signal producer by sharing one produced signal

If multiple observers are interested in the results of a signal producer, calling start once for each observer means that the work associated with the producer will execute that many times and may not generate the same results.

If:

1. the observers need to receive the exact same results
2. the observers know about each other, or
3. the code starting the producer knows about each observer

… it may be more appropriate to start the producer just once, and share the results of that one signal to all observers, by attaching them within the closure passed to the startWithSignal method.

Prefer managing lifetime with operators over explicit disposal

Although the disposable returned from start makes canceling a signal producer really easy, explicit use of disposables can quickly lead to a rat's nest of resource management and cleanup code.

There are almost always higher-level operators that can be used instead of manual disposal:

• take can be used to automatically terminate a stream once a certain number of values have been received.
• takeUntil can be used to automatically terminate a signal or producer when an event occurs (for example, when a “Cancel” button is pressed in the UI).
• Properties and the <~ operator can be used to “bind” the result of a signal or producer, until termination or until the property is deallocated. This can replace a manual observation that sets a value somewhere.

Implementing new operators

RAC provides a long list of built-in operators that should cover most use cases; however, RAC is not a closed system. It's entirely valid to implement additional operators for specialized uses, or for consideration in ReactiveCocoa itself.

Implementing a new operator requires a careful attention to detail and a focus on simplicity, to avoid introducing bugs into the calling code.

These guidelines cover some of the common pitfalls and help preserve the expected API contracts. It may also help to look at the implementations of existing Signal and SignalProducer operators for reference points.

Prefer writing operators that apply to both signals and producers

Since any signal operator can apply to signal producers, writing custom operators in terms of Signal means that SignalProducer will get it “for free.”

Even if the caller only needs to apply the new operator to signal producers at first, this generality can save time and effort in the future.

Of course, some capabilities require producers (for example, any retrying or repeating), so it may not always be possible to write a signal-based version instead.

Compose existing operators when possible

Considerable thought has been put into the operators provided by RAC, and they have been validated through automated tests and through their real world use in other projects. An operator that has been written from scratch may not be as robust, or might not handle a special case that the built-in operators are aware of.

To minimize duplication and possible bugs, use the provided operators as much as possible in a custom operator implementation. Generally, there should be very little code written from scratch.

Forward failure and interruption events as soon as possible

Unless an operator is specifically built to handle failures and interruption in a custom way, it should propagate those events to the observer as soon as possible, to ensure that their semantics are honored.

Switch over Event values

Instead of using start(failed:completed:interrupted:next:) or observe(failed:completed:interrupted:next:), create your own observer to process raw Event values, and use a switch statement to determine the event type.

For example:

producer.start { event in
    switch event {
    case let .Next(value):
        print("Next event: \(value)")

    case let .Failed(error):
        print("Failed event: \(error)")

    case .Completed:
        print("Completed event")

    case .Interrupted:
        print("Interrupted event")
    }
}

Since the compiler will generate a warning if the switch is missing any case, this prevents mistakes in a custom operator’s event handling.

Avoid introducing concurrency

Concurrency is an extremely common source of bugs in programming. To minimize the potential for deadlocks and race conditions, operators should not concurrently perform their work.

Callers always have the ability to observe events on a specific scheduler, and RAC offers built-in ways to parallelize work, so custom operators don’t need to be concerned with it.

Avoid blocking in operators

Signal or producer operators should return a new signal or producer (respectively) as quickly as possible. Any work that the operator needs to perform should be part of the event handling logic, not part of the operator invocation itself.

This guideline can be safely ignored when the purpose of an operator is to synchronously retrieve one or more values from a stream, like single() or wait().