Action

public final class Action<Input, Output, Error> where Error : Error
extension Action: BindingTargetProvider

Action represents a repeatable work like SignalProducer. But on top of the isolation of produced Signals from a SignalProducer, Action provides higher-order features like availability and mutual exclusion.

Similar to a produced Signal from a SignalProducer, each unit of the repreatable work may output zero or more values, and terminate with or without an error at some point.

The core of Action is the execute closure it created with. For every execution attempt with a varying input, if the Action is enabled, it would request from the execute closure a customized unit of work — represented by a SignalProducer. Specifically, the execute closure would be supplied with the latest state of Action and the external input from apply().

Action enforces serial execution, and disables the Action during the execution.

  • The lifetime of the Action.

    Declaration

    Swift

    public let lifetime: Lifetime

  • A signal of all events generated from all units of work of the Action.

    In other words, this sends every Event from every unit of work that the Action executes.

    Declaration

    Swift

    public let events: Signal<Signal<Output, Error>.Event, Never>

  • A signal of all values generated from all units of work of the Action.

    In other words, this sends every value from every unit of work that the Action executes.

    Declaration

    Swift

    public let values: Signal<Output, Never>

  • A signal of all errors generated from all units of work of the Action.

    In other words, this sends every error from every unit of work that the Action executes.

    Declaration

    Swift

    public let errors: Signal<Error, Never>

  • A signal of all failed attempts to start a unit of work of the Action.

    Declaration

    Swift

    public let disabledErrors: Signal<(), Never>

  • A signal of all completed events generated from applications of the action.

    In other words, this will send completed events from every signal generated by each SignalProducer returned from apply().

    Declaration

    Swift

    public let completed: Signal<(), Never>

  • Whether the action is currently executing.

    Declaration

    Swift

    public let isExecuting: Property<Bool>

  • Whether the action is currently enabled.

    Declaration

    Swift

    public let isEnabled: Property<Bool>

  • Initializes an Action that would be conditionally enabled depending on its state.

    When the Action is asked to start the execution with an input value, a unit of work — represented by a SignalProducer — would be created by invoking execute with the latest state and the input value.

    Note

    Action guarantees that changes to state are observed in a thread-safe way. Thus, the value passed to isEnabled will always be identical to the value passed to execute, for each application of the action.

    Note

    This initializer should only be used if you need to provide custom input can also influence whether the action is enabled. The various convenience initializers should cover most use cases.

    Declaration

    Swift

    public init<State: PropertyProtocol>(state: State, enabledIf isEnabled: @escaping (State.Value) -> Bool, execute: @escaping (State.Value, Input) -> SignalProducer<Output, Error>)

    Parameters

    state

    A property to be the state of the Action.
    isEnabled

    A predicate which determines the availability of the Action, given the latest Action state.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that uses a property as its state.

    When the Action is asked to start the execution, a unit of work — represented by a SignalProducer — would be created by invoking execute with the latest value of the state.

    Declaration

    Swift

    public convenience init<P: PropertyProtocol>(state: P, execute: @escaping (P.Value, Input) -> SignalProducer<Output, Error>)

    Parameters

    state

    A property to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that would be conditionally enabled.

    When the Action is asked to start the execution with an input value, a unit of work — represented by a SignalProducer — would be created by invoking execute with the input value.

    Declaration

    Swift

    public convenience init<P: PropertyProtocol>(enabledIf isEnabled: P, execute: @escaping (Input) -> SignalProducer<Output, Error>) where P.Value == Bool

    Parameters

    isEnabled

    A property which determines the availability of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that uses a property of optional as its state.

    When the Action is asked to start executing, a unit of work (represented by a SignalProducer) is created by invoking execute with the latest value of the state and the input that was passed to apply().

    If the property holds a nil, the Action would be disabled until it is not nil.

    Declaration

    Swift

    public convenience init<P: PropertyProtocol, T>(unwrapping state: P, execute: @escaping (T, Input) -> SignalProducer<Output, Error>) where P.Value == T?

    Parameters

    state

    A property of optional to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that uses a ValidatingProperty as its state.

    When the Action is asked to start executing, a unit of work (represented by a SignalProducer) is created by invoking execute with the latest value of the state and the input that was passed to apply().

    If the ValidatingProperty does not hold a valid value, the Action would be disabled until it’s valid.

    Declaration

    Swift

    public convenience init<T, E>(validated state: ValidatingProperty<T, E>, execute: @escaping (T, Input) -> SignalProducer<Output, Error>)

    Parameters

    state

    A ValidatingProperty to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that would always be enabled.

    When the Action is asked to start the execution with an input value, a unit of work — represented by a SignalProducer — would be created by invoking execute with the input value.

    Declaration

    Swift

    public convenience init(execute: @escaping (Input) -> SignalProducer<Output, Error>)

    Parameters

    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Create a SignalProducer that would attempt to create and start a unit of work of the Action. The SignalProducer would forward only events generated by the unit of work it created.

    If the execution attempt is failed, the producer would fail with ActionError.disabled.

    Declaration

    Swift

    public func apply(_ input: Input) -> SignalProducer<Output, ActionError<Error>>

    Parameters

    input

    A value to be used to create the unit of work.

    Return Value

    A producer that forwards events generated by its started unit of work, or emits ActionError.disabled if the execution attempt is failed.

Available where Input == Void

  • Create a SignalProducer that would attempt to create and start a unit of work of the Action. The SignalProducer would forward only events generated by the unit of work it created.

    If the execution attempt is failed, the producer would fail with ActionError.disabled.

    Declaration

    Swift

    public func apply() -> SignalProducer<Output, ActionError<Error>>

    Return Value

    A producer that forwards events generated by its started unit of work, or emits ActionError.disabled if the execution attempt is failed.

  • Initializes an Action that uses a property of optional as its state.

    When the Action is asked to start the execution, a unit of work — represented by a SignalProducer — would be created by invoking execute with the latest value of the state.

    If the property holds a nil, the Action would be disabled until it is not nil.

    Declaration

    Swift

    public convenience init<P: PropertyProtocol, T>(unwrapping state: P, execute: @escaping (T) -> SignalProducer<Output, Error>) where P.Value == T?

    Parameters

    state

    A property of optional to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that uses a ValidatingProperty as its state.

    When the Action is asked to start executing, a unit of work (represented by a SignalProducer) is created by invoking execute with the latest value of the state and the input that was passed to apply().

    If the ValidatingProperty does not hold a valid value, the Action would be disabled until it’s valid.

    Declaration

    Swift

    public convenience init<T, E>(validated state: ValidatingProperty<T, E>, execute: @escaping (T) -> SignalProducer<Output, Error>)

    Parameters

    state

    A ValidatingProperty to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.

  • Initializes an Action that uses a property as its state.

    When the Action is asked to start the execution, a unit of work — represented by a SignalProducer — would be created by invoking execute with the latest value of the state.

    Declaration

    Swift

    public convenience init<P: PropertyProtocol, T>(state: P, execute: @escaping (T) -> SignalProducer<Output, Error>) where P.Value == T

    Parameters

    state

    A property to be the state of the Action.
    execute

    A closure that produces a unit of work, as SignalProducer, to be executed by the Action.