FutureProtocol

public protocol FutureProtocol : CustomDebugStringConvertible, CustomReflectable

A future models reading a value which may become available at some point.

A FutureProtocol may be preferable to an architecture using completion handlers; separating the mechanism for handling the completion from the call that began it leads to a more readable code flow.

A future is primarily useful as a joining mechanism for asynchronous operations. Though the protocol requires a synchronous accessor, its use is not recommended outside of testing. upon is preferred for nearly all access:

myFuture.upon(.main) { value in
  print("I now have the value: \(value)")
}

FutureProtocol makes no requirement on conforming types regarding thread-safe access, though ideally all members of the future could be called from any thread.

  • A type that represents the result of some asynchronous operation.

    Declaration

    Swift

    associatedtype Value
  • upon(_:execute:) Default implementation

    Call some body closure once the value is determined.

    If the value is determined, the closure should be submitted to the executor immediately.

    Default Implementation

    Call some body closure in the background once the value is determined.

    If the value is determined, the closure will be enqueued immediately, but this call is always asynchronous.

    Declaration

    Swift

    func upon(_ executor: Executor, execute body: @escaping(Value) -> Void)
  • peek() Default implementation

    Checks for and returns a determined value.

    An implementation should use a best effort to return this value and not unnecessarily block in order to to return.

    Default Implementation

    By default, calls wait with no delay.

    Declaration

    Swift

    func peek() -> Value?

    Return Value

    The determined value, if already filled, or nil.

  • Waits synchronously for the value to become determined.

    If the value is already determined, the call returns immediately with the value.

    Declaration

    Swift

    func wait(until time: DispatchTime) -> Value?

    Parameters

    time

    A deadline for the value to be determined.

    Return Value

    The determined value, if filled within the timeout, or nil.

Default implementations
  • debugDescription Extension method

    A textual representation of this instance, suitable for debugging.

    Declaration

    Swift

    public var debugDescription: String { get }
  • customMirror Extension method

    Return the Mirror for self.

    Declaration

    Swift

    public var customMirror: Mirror { get }
  • andThen(upon:start:) Extension method

    Begins another asynchronous operation by passing the deferred value to requestNextValue once it becomes determined.

    andThen is similar to map, but requestNextValue returns another future instead of an immediate value. Use andThen when you want the reciever to feed into another asynchronous operation. You might hear this referred to as chaining or binding.

    Declaration

    Swift

    public func andThen<NewFuture: FutureProtocol>(upon executor: PreferredExecutor, start requestNextValue: @escaping(Value) -> NewFuture) -> Future<NewFuture.Value>
  • andThen(upon:start:) Extension method

    Begins another asynchronous operation by passing the deferred value to requestNextValue once it becomes determined.

    andThen is similar to map, but requestNextValue returns another future instead of an immediate value. Use andThen when you want the reciever to feed into another asynchronous operation. You might hear this referred to as chaining or binding.

    Note

    It is important to keep in mind the thread safety of the requestNextValue closure. Creating a new asynchronous task typically involves state. Ensure the function is compatible with executor.

    Declaration

    Swift

    public func andThen<NewFuture: FutureProtocol>(upon executor: Executor, start requestNextValue: @escaping(Value) -> NewFuture) -> Future<NewFuture.Value>

    Parameters

    executor

    Context to execute the transformation on.
    requestNextValue

    Start a new operation with the future value.

    Return Value

    The new deferred value returned by the transform.

  • and(_:) Extension method

    Returns a value that becomes determined after both the callee and the given future become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1>(_ one: Other1) -> Future<(Value, Other1.Value)> where Other1 : FutureProtocol
  • and(_:_:) Extension method

    Returns a value that becomes determined after the callee and both other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2>(_ one: Other1, _ two: Other2) -> Future<(Value, Other1.Value, Other2.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol
  • and(_:_:_:) Extension method

    Returns a value that becomes determined after the callee and all other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2, Other3>(_ one: Other1, _ two: Other2, _ three: Other3) -> Future<(Value, Other1.Value, Other2.Value, Other3.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol, Other3 : FutureProtocol
  • and(_:_:_:_:) Extension method

    Returns a value that becomes determined after the callee and all other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2, Other3, Other4>(_ one: Other1, _ two: Other2, _ three: Other3, _ four: Other4) -> Future<(Value, Other1.Value, Other2.Value, Other3.Value, Other4.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol, Other3 : FutureProtocol, Other4 : FutureProtocol
  • and(_:_:_:_:_:) Extension method

    Returns a value that becomes determined after the callee and all other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2, Other3, Other4, Other5>(_ one: Other1, _ two: Other2, _ three: Other3, _ four: Other4, _ five: Other5) -> Future<(Value, Other1.Value, Other2.Value, Other3.Value, Other4.Value, Other5.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol, Other3 : FutureProtocol, Other4 : FutureProtocol, Other5 : FutureProtocol
  • and(_:_:_:_:_:_:) Extension method

    Returns a value that becomes determined after the callee and all other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2, Other3, Other4, Other5, Other6>(_ one: Other1, _ two: Other2, _ three: Other3, _ four: Other4, _ five: Other5, _ six: Other6) -> Future<(Value, Other1.Value, Other2.Value, Other3.Value, Other4.Value, Other5.Value, Other6.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol, Other3 : FutureProtocol, Other4 : FutureProtocol, Other5 : FutureProtocol, Other6 : FutureProtocol
  • and(_:_:_:_:_:_:_:) Extension method

    Returns a value that becomes determined after the callee and all other futures become determined.

    See

    SequenceType.allFilled()

    Declaration

    Swift

    public func and<Other1, Other2, Other3, Other4, Other5, Other6, Other7>(_ one: Other1, _ two: Other2, _ three: Other3, _ four: Other4, _ five: Other5, _ six: Other6, _ seven: Other7) -> Future<(Value, Other1.Value, Other2.Value, Other3.Value, Other4.Value, Other5.Value, Other6.Value, Other7.Value)> where Other1 : FutureProtocol, Other2 : FutureProtocol, Other3 : FutureProtocol, Other4 : FutureProtocol, Other5 : FutureProtocol, Other6 : FutureProtocol, Other7 : FutureProtocol
  • every(per:) Extension method

    Returns a future that transparently performs the eachUseTransform while reusing the original future.

    The upon(_:execute:) and wait(until:) methods of the returned future forward to self, wrapping access to the underlying value by the transform.

    Though producing similar results, this method does not work like map, which eagerly evaluates the transform to create a new future with new storage. This is not suitable for simple transforms, such as unboxing or conversion.

    See

    map(upon:transform:)

    Declaration

    Swift

    public func every<NewValue>(per eachUseTransform: @escaping(Value) -> NewValue) -> Future<NewValue>
  • ignored() Extension method

    Returns a future that ignores the result of this future.

    This is semantically identical to the following:

    myFuture.map { _ in }

    But may behave more efficiently.

    See

    map(upon:transform:)

    Declaration

    Swift

    public func ignored() -> Future<Void>
  • map(upon:transform:) Extension method

    Returns a future containing the result of mapping transform over the deferred value.

    Declaration

    Swift

    public func map<NewValue>(upon executor: PreferredExecutor, transform: @escaping(Value) -> NewValue) -> Future<NewValue>
  • map(upon:transform:) Extension method

    Returns a future containing the result of mapping transform over the deferred value.

    map submits the transform to the executor once the future’s value is determined.

    Declaration

    Swift

    public func map<NewValue>(upon executor: Executor, transform: @escaping(Value) -> NewValue) -> Future<NewValue>

    Parameters

    executor

    Context to execute the transformation on.
    transform

    Creates something using the deferred value.

    Return Value

    A new future that is filled once the receiver is determined.

  • defaultUponExecutor Extension method

    The executor to use as a default argument to upon methods on Future.

    Don’t provide a default parameter using this declaration unless doing so is unambiguous. For instance, map and andThen once had a default executor, but users found it unclear wherethe handlers executed.

    Declaration

    Swift

    public static var defaultUponExecutor: PreferredExecutor { get }