Contents

Publisher

Declares that a type can transmit a sequence of values over time.

Declaration

protocol Publisher<Output, Failure>

Mentioned in

Overview

A publisher delivers elements to one or more Subscriber instances. The subscriber’s Input and Failure associated types must match the Output and Failure types declared by the publisher. The publisher implements the receive(subscriber:)method to accept a subscriber.

After this, the publisher can call the following methods on the subscriber:

  • receive(subscription:): Acknowledges the subscribe request and returns a Subscription instance. The subscriber uses the subscription to demand elements from the publisher and can use it to cancel publishing.

  • receive(_:): Delivers one element from the publisher to the subscriber.

  • receive(completion:): Informs the subscriber that publishing has ended, either normally or with an error.

Every Publisher must adhere to this contract for downstream subscribers to function correctly.

Using operators

Extensions on Publisher define a wide variety of operators that you compose to create sophisticated event-processing chains. Each operator returns a type that implements the Publisher protocol Most of these types exist as extensions on the Publishers enumeration. For example, the map(_:) operator returns an instance of Publishers.Map.

Use operators to assemble a chain of republishers, optionally ending with a subscriber, that processes elements produced by upstream publishers. Each operator creates and configures an instance of a Publisher or Subscriber, and subscribes it to the publisher that you call the method on.

In the following example, a sequence publisher emits the integers 1, 2, 3, 4, and 5. A filter(_:) operator creates a Publishers.Filter publisher to only republish even values. A second operator creates a Subscribers.Sink subscriber to print out each value received. The sink subscriber automatically subscribes to the filter publisher, at which point the filter publisher subscribes to its upstream publisher, the sequence publisher.

let cancellable = [1, 2, 3, 4, 5].publisher
    .filter {
        $0 % 2 == 0
    }
    .sink {
        print ("Even number: \($0)")
    }
// Prints:
// Even number: 2
// Even number: 4

Creating Your Own Publishers

Rather than implementing the Publisher protocol yourself, you can create your own publisher by using one of several types provided by the Combine framework:

  • Use a concrete subclass of Subject, such as PassthroughSubject, to publish values on-demand by calling its send(_:) method.

  • Use a CurrentValueSubject to publish whenever you update the subject’s underlying value.

  • Add the @Published annotation to a property of one of your own types. In doing so, the property gains a publisher that emits an event whenever the property’s value changes. See the Published type for an example of this approach.

Topics

Declaring supporting types

Working with subscribers

Mapping elements

Filtering elements

Reducing elements

Applying mathematical operations on elements

Applying matching criteria to elements

Applying sequence operations to elements

Selecting specific elements

Collecting and republishing the latest elements from multiple publishers

Republishing elements from multiple publishers as an interleaved stream

Collecting and republishing the oldest unconsumed elements from multiple publishers

Republishing elements by subscribing to new publishers

Handling errors

Controlling timing

Encoding and decoding

Identifying properties with key paths

Working with multiple subscribers

Buffering elements

Performing type erasure

Specifying schedulers

Adding explicit connectability

Connecting simple subscribers

Accessing elements asynchronously

Debugging

See Also

Publishers