Future

public enum Future

A namespace for types and convenience methods related to futures.

For details on futures, see FutureProtocol.

Creating Futures

  • Creates a future that never completes.

    let f = Future.never(outputType: Void.self)
f.wait() // will block forever

    Declaration

    Swift

    @inlinable
public static func never<T>(outputType _: T.Type = T.self) -> Future._Private.Never<T>

    Return Value

    some FutureProtocol<Output == Void>

    Show on GitHub

  • Creates a future that completes immediately.

    let f = Future.ready()
assert(f.wait() == ())

    Declaration

    Swift

    @inlinable
public static func ready() -> Future._Private.Ready<Void>

    Return Value

    some FutureProtocol<Output == Void>

    Show on GitHub

  • Creates a future that completes immediately with the given value.

    let f = Future.ready(42)
assert(f.wait() == 42)

    Declaration

    Swift

    @inlinable
public static func ready<T>(_ output: T) -> Future._Private.Ready<T>

    Return Value

    some FutureProtocol<Output == T>

    Show on GitHub

  • Creates a future that lazily invokes the given closure, awaits the returned future and completes with that future’s value.

    let f = Future.lazy {
    Future.ready(42)
}
assert(f.wait() == 42)

    Declaration

    Swift

    @inlinable
public static func `lazy`<U>(_ body: @escaping () -> U) -> Future._Private.Lazy<U>

    Return Value

    some FutureProtocol<Output == U.FutureType.Output>

    Show on GitHub

Combining Output from Multiple Futures

  • Creates a future that collects the output from a sequence of futures that output elements of the same type and completes with an array of the elements when all futures complete.

    This combinator can efficiently handle arbitrary numbers of futures but has more overhead than the simpler join(_:_:) variants.

    let f = Future.joinAll([
    Future.ready(1),
    Future.ready(2),
    Future.ready(3),
])
assert(f.wait() == [1, 2, 3])

    Declaration

    Swift

    @inlinable
public static func joinAll<C>(_ futures: C) -> Future._Private.JoinAll<C.Element.FutureType>
    where C: Sequence, C.Element: FutureConvertible

    Return Value

    some FutureProtocol<Output == [C.Element.FutureType.Output]>

    Show on GitHub

  • Declaration

    Swift

    @inlinable
public static func joinAll<F>(_ futures: F...) -> Future._Private.JoinAll<F> where F : FutureProtocol

    Return Value

    some FutureProtocol<Output == [F.Output]>

    Show on GitHub

  • Creates a future that combines the output from two futures by waiting until both futures complete and then completing with the output from each future together as a tuple.

    let a = Future.ready(1)
let b = Future.ready("A")
let f = Future.join(a, b)
assert(f.wait() == (1, "A"))

    Declaration

    Swift

    @inlinable
public static func join<A, B>(_ a: A, _ b: B) -> Future._Private.Join<A, B> where A : FutureProtocol, B : FutureProtocol

    Return Value

    some FutureProtocol<Output == (A.Output, B.Output)>

    Show on GitHub

  • Creates a future that combines the output from three futures by waiting until all futures complete and then completing with the output from each future together as a tuple.

    let a = Future.ready(1)
let b = Future.ready("A")
let c = Future.ready("X")
let f = Future.join(a, b, c)
assert(f.wait() == (1, "A", "X"))

    Declaration

    Swift

    @inlinable
public static func join<A, B, C>(_ a: A, _ b: B, _ c: C) -> Future._Private.Join3<A, B, C> where A : FutureProtocol, B : FutureProtocol, C : FutureProtocol

    Return Value

    some FutureProtocol<Output == (A.Output, B.Output, C.Output)>

    Show on GitHub

  • Creates a future that combines the output from four futures by waiting until all futures complete and then completing with the output from each future together as a tuple.

    let a = Future.ready(1)
let b = Future.ready("A")
let c = Future.ready("X")
let d = Future.ready(5)
let f = Future.join(a, b, c, d)
assert(f.wait() == (1, "A", "X", 5))

    Declaration

    Swift

    @inlinable
public static func join<A, B, C, D>(_ a: A, _ b: B, _ c: C, _ d: D) -> Future._Private.Join4<A, B, C, D> where A : FutureProtocol, B : FutureProtocol, C : FutureProtocol, D : FutureProtocol

    Return Value

    some FutureProtocol<Output == (A.Output, B.Output, C.Output, D.Output)>

    Show on GitHub

  • Creates a future that waits until any of the given sequence of futures that output elements of the same type completes, and completes with the output from that future.

    This combinator can efficiently handle arbitrary numbers of futures but has more overhead than the simpler select(_:_:) variant.

    let f = Future.selectAny([
    Future.ready(1),
    Future.ready(2),
    Future.ready(3),
])
assert(f.wait() == 1)

    Declaration

    Swift

    @inlinable
public static func selectAny<C>(_ futures: C) -> Future._Private.SelectAny<C.Element.FutureType>
    where C: Sequence, C.Element: FutureConvertible

    Return Value

    some FutureProtocol<Output == C.Element.FutureType.Output>

    Show on GitHub

  • Declaration

    Swift

    @inlinable
public static func selectAny<F>(_ futures: F...) -> Future._Private.SelectAny<F> where F : FutureProtocol

    Return Value

    some FutureProtocol<Output == F.Output>

    Show on GitHub

  • Creates a future that waits until either of the given futures complete, and completes with the output from that future.

    let a = Future.ready(1)
let b = Future.ready("A")
let f = Future.select(a, b)
assert(f.wait() == .left(1))

    Declaration

    Swift

    @inlinable
public static func select<A, B>(_ a: A, _ b: B) -> Future._Private.Select<A, B> where A : FutureProtocol, B : FutureProtocol

    Return Value

    some FutureProtocol<Output == Either<A.Output, B.Output>>

    Show on GitHub

Creating Failable Futures

  • Creates a future that lazily invokes the given error-throwing closure, awaits the returned future and completes with that future’s output.

    let f = Future.tryLazy {
    Future.ready(42)
}
assert(try? f.wait().get() == 42)

    Declaration

    Swift

    @inlinable
public static func tryLazy<U>(_ body: @escaping () throws -> U) -> Future._Private.TryLazy<U>

    Return Value

    some FutureProtocol<Output == Result<U.FutureType.Output, Error>>

    Show on GitHub