Future

public class Future<T> : FutureProtocol

Future<T>

A Future is a swift generic class that let’s you represent an object that will be returned at somepoint in the future. Usually from some asynchronous operation that may be running in a different thread/dispatch_queue or represent data that must be retrieved from a remote server somewhere.

  • returns: the current completion value of the Future

    accessing this variable directly requires thread synchronization.

    It is more efficient to examine completion values that are sent to an onComplete/onSuccess handler of a future than to examine it directly here.

    type of synchronization used can be configured via GLOBAL_PARMS.LOCKING_STRATEGY

    Declaration

    Swift

    public final var result : FutureResult<T>?
  • returns: the result of the Future iff the future has completed successfully. returns nil otherwise.

    accessing this variable directly requires thread synchronization.

    Declaration

    Swift

    public var value : T?
  • returns: the error of the Future iff the future has completed with an Error. returns nil otherwise.

    accessing this variable directly requires thread synchronization.

    Declaration

    Swift

    public var error : ErrorType?
  • is true if the Future supports cancellation requests using cancel()

    May return true, even if the Future has already been completed, and cancellation is no longer possible.

    It only informs the user that this type of future can be cancelled.

    Declaration

    Swift

    public var cancellationIsSupported : Bool
  • returns: true if the Future has completed with any completion value.

    accessing this variable directly requires thread synchronization.

    Declaration

    Swift

    public final var isCompleted : Bool
  • creates a completed Future.

    Declaration

    Swift

    public init(completed:FutureResult<T>) {  // returns an completed Task
  • creates a completed Future with a completion == .Success(success)

    Declaration

    Swift

    public init(success:T) {  // returns an completed Task  with result T
  • creates a completed Future with a completion == .Error(failed)

    Declaration

    Swift

    public init(failed:ErrorType) {  // returns an completed Task that has Failed with this error
  • creates a completed Future with a completion == .Error(FutureNSError(failWithErrorMessage))

    Declaration

    Swift

    public init(failWithErrorMessage errorMessage: String)
  • creates a completed Future with a completion == .Error(FutureNSError(exception))

    Declaration

    Swift

    public init(exception:NSException) {  // returns an completed Task that has Failed with this error
  • creates a completed Future with a completion == .Cancelled(cancelled)

    Declaration

    Swift

    public init(cancelled:()) {  // returns an completed Task that has Failed with this error
  • creates a completed Future with a completion == .Cancelled(cancelled)

    Declaration

    Swift

    public init(future f:Future<T>) {  // returns an completed Task that has Failed with this error
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Creates a future by executes block inside of an Executor, and when it’s complete, sets the completion = .Success(block())

    can only be used to a create a Future that should always succeed.

    Declaration

    Swift

    public init(_ executor : Executor, block: () throws -> T)
  • Creates a future by executes block inside of an Executor, and when it’s complete, sets the completion = block()

    can be used to create a Future that may succeed or fail.

    the block can return a value of .CompleteUsing(Future) if it wants this Future to complete with the results of another future.

    Declaration

    Swift

    public init(_ executor : Executor, block: () throws -> Completion<T>)
  • Creates a future by executes block inside of an Executor, and when it’s complete, sets the completion = block()

    can be used to create a Future that may succeed or fail.

    the block can return a value of .CompleteUsing(Future) if it wants this Future to complete with the results of another future.

    Declaration

    Swift

    public init(block: () throws -> Completion<T>)
  • if we try to convert a future from type T to type T, just ignore the request.

    the compile should automatically figure out which version of As() execute

    Declaration

    Swift

    public final func As() -> Future<T>
  • if we try to convert a future from type T to type T, just ignore the request.

    the swift compiler can automatically figure out which version of mapAs() execute

    Declaration

    Swift

    public final func mapAs() -> Future<T>
  • convert this future of type Future<T> into another future type Future<__Type>

    WARNING: if T as! __Type isn’t legal, than your code may generate an exception.

    works iff the following code works:

    let t : T
    let s = t as! __Type
    

    example:

    let f = Future<Int>(success:5)
    let f2 : Future<Int32> = f.As()
    assert(f2.result! == Int32(5))
    

    you will need to formally declare the type of the new variable in order for Swift to perform the correct conversion.

    the following conversions should always work for any future

    let fofany : Future<Any> = f.As()
    let fofvoid: Future<Void> = f.As()
    

    Declaration

    Swift

    public final func As<__Type>() -> Future<__Type>

    Return Value

    a new Future of with the result type of __Type

  • convert this future of type Future<T> into another future type Future<__Type>

    WARNING: if T as! __Type isn’t legal, than your code may generate an exception.

    works iff the following code works:

    let t : T let s = t as! __Type

    example:

    let f = Future(success:5) let f2 : Future = f.As() assert(f2.result! == Int32(5))

    you will need to formally declare the type of the new variable in order for Swift to perform the correct conversion.

    the following conversions should always work for any future

    let fofany : Future = f.As() let fofvoid: Future = f.As()

    Declaration

    Swift

    public final func mapAs<__Type>() -> Future<__Type>

    Return Value

    a new Future of with the result type of __Type

  • convert Future<T> into another type Future<__Type?>.

    WARNING: if T as! __Type isn’t legal, than all Success values may be converted to nil

    example:

    let f = Future<String>(success:"5")
    let f2 : Future<[Int]?> = f.convertOptional()
    assert(f2.result! == nil)
    

    you will need to formally declare the type of the new variable (ex: f2), in order for Swift to perform the correct conversion.

    Declaration

    Swift

    public final func convertOptional<__Type>() -> Future<__Type?>

    Return Value

    a new Future of with the result type of __Type?

  • convert Future<T> into another type Future<__Type?>.

    WARNING: if T as! __Type isn’t legal, than all Success values may be converted to nil

    example:

    let f = Future(success:5) let f2 : Future<[Int]?> = f.convertOptional() assert(f2.result! == nil)

    you will need to formally declare the type of the new variable (ex: f2), in order for Swift to perform the correct conversion.

    Declaration

    Swift

    public final func mapAsOptional<__Type>() -> Future<__Type?>

    Return Value

    a new Future of with the result type of __Type?

  • executes a block using the supplied Executor if and when the target future is completed. Will execute immediately if the target is already completed.

    This method will let you examine the completion state of target, and return a new future in any completion state, with the user defined type __Type.

    The completion argument will be set to the Completion value that completed the target. It will be one of 3 values (.Success, .Fail, or .Cancelled).

    The block must return one of four enumeration values (.Success/.Fail/.Cancelled/.CompleteUsing).

    Returning a future f using .CompleteUsing(f) causes the future returned from this method to be completed when f completes, using the completion value of f. (Leaving the Future in an incomplete state, until ‘f’ completes).

    The new future returned from this function will be completed using the completion value returned from this block.

    Declaration

    Swift

    public final func onComplete<__Type>(executor : Executor = .Primary,block:(result:FutureResult<T>) throws -> Completion<__Type>) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that will execute when this future completes, and returns a new completion value for the new completion type. The block must return a Completion value (Completion<__Type>).

    Return Value

    a new Future that returns results of type Type (Future<Type>)

  • executes a block using the supplied Executor if and when the target future is completed. Will execute immediately if the target is already completed.

    This method will let you examine the completion state of target, and return a new future that completes with a .Success(result). The value returned from the block will be set as this Future’s result.

    Declaration

    Swift

    public final func onComplete<__Type>(executor: Executor = .Primary, block:(result:FutureResult<T>) throws -> FutureResult<__Type>) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that will execute when this future completes, a .Success(result) using the return value of the block.

    Return Value

    a new Future that returns results of type __Type

  • executes a block using the supplied Executor if and when the target future is completed. Will execute immediately if the target is already completed.

    This method will let you examine the completion state of target, and return a new future that completes with a .Success(result). The value returned from the block will be set as this Future’s result.

    Declaration

    Swift

    public final func onComplete<__Type>(executor: Executor = .Primary, block:(result:FutureResult<T>) throws -> __Type) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that will execute when this future completes, a .Success(result) using the return value of the block.

    Return Value

    a new Future that returns results of type __Type

  • takes a block and executes it if and when this future is completed. The block will be executed using supplied Executor.

    The new future returned from this function will be completed with `.Success’.

    Declaration

    Swift

    public final func onComplete(executor: Executor = .Primary, block:(result:FutureResult<T>) throws -> Void) -> Future<Void>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that will execute when this future completes.

    Return Value

    a Future<Void> that completes after this block has executed.

  • takes a block and executes it if and when this future is completed. The block will be executed using supplied Executor.

    The new future returned from this function will be completed when the future returned from the block is completed.

    This is the same as returning Completion.CompleteUsing(f)

    Declaration

    Swift

    public final func onComplete<__Type>
                (executor: Executor = .Primary,
                block:(result:FutureResult<T>) throws -> Future<__Type>) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that will execute when this future completes, and return a new Future.

    Return Value

    a Future<Void> that completes after this block has executed.

  • takes a two block and executes one or the other. the didComplete() block will be executed if the target completes prior before the timeout.

    it if and when this future is completed. The block will be executed using supplied Executor.

    The new future returned from this function will be completed when the future returned from the block is completed.

    This is the same as returning Completion.CompleteUsing(f)

    Declaration

    Swift

    public func waitForComplete<__Type>(timeout: NSTimeInterval,
            executor : Executor,
            didComplete:(FutureResult<T>)-> Completion<__Type>,
            timedOut:()-> Completion<__Type>
            ) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    didComplete

    a block that will execute if this future completes. It will return a completion value that

    Return Value

    a Future<Void> that completes after this block has executed.

  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • takes a block and executes it iff the target is completed with a .Success

    If the target is completed with a .Success, then the block will be executed using the supplied Executor. The new future returned from this function will be completed using the completion value returned from this block.

    If the target is completed with a .Fail, then the returned future will also complete with .Fail and this block will not be executed.

    If the target is completed with a .Cancelled, then the returned future will also complete with .Cancelled and this block will not be executed.

    Warning - as of swift 1.2, you can’t use this method with a Future (it will give a compiler error). Instead use onAnySuccess()

    Declaration

    Swift

    public final func onSuccess<__Type>(executor : Executor = .Primary,
            block:(T) throws -> Completion<__Type>) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block takes the .Success result of the target Future and returns the completion value of the returned Future.

    Return Value

    a new Future of type Future<__Type>

  • takes a block and executes it if the target is completed with a .Success

    If the target is completed with a .Success, then the block will be executed using the supplied Executor.

    Declaration

    Swift

    public final func onSuccess(executor : Executor = .Primary,
            block:(T) throws -> Void) -> Future<Void>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block takes the .Success result of the target Future and returns the completion value of the returned Future.

    Return Value

    a Future<Void> that completes after this block has executed.

  • takes a block and executes it iff the target is completed with a .Success.

    Currently, in swift 2.0, this is the only way to add a Success handler to a future of type Future<Void> or Future<()>. But can be used with Future’s of all types. All results are converted to Any in your code. This can be used as the ‘type-unsafe’ version of OnSuccess

    If the target is completed with a .Success, then the block will be executed using the supplied Executor. The future returned from this function will be completed using the value returned from this block.

    If the target is completed with a .Fail, then the returned future will also complete with .Fail and this block will not be executed.

    If the target is completed with a .Cancelled, then the returned future will also complete with .Cancelled and this block will not be executed.

    Declaration

    Swift

    public final func onAnySuccess<__Type>(executor : Executor = .Primary,
            block:(Any) throws -> Completion<__Type>) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block that returns the completion value of the returned Future.

    Return Value

    a new future of type Future<__Type>

  • takes a block and executes it iff the target is completed with a .Fail

    If the target is completed with a .Fail, then the block will be executed using the supplied Executor.

    This method does not return a new Future. If you need a new future, than use onComplete() instead.

    Declaration

    Swift

    public final func onFail(executor : Executor = .Primary,
            block:(error:ErrorType)-> Void)

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block can process the error of a future.

  • takes a block and executes it iff the target is completed with a .Cancelled

    If the target is completed with a .Cancelled, then the block will be executed using the supplied Executor.

    This method does not return a new Future. If you need a new future, than use onComplete() instead.

    Declaration

    Swift

    public final func onCancel(executor : Executor = .Primary, block:()-> Void)

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block takes the canceltoken returned by the target Future and returns the completion value of the returned Future.

  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • takes a block and executes it iff the target is completed with a .Success

    If the target is completed with a .Success, then the block will be executed using the supplied Executor.

    The new future returned from this function will be completed with .Success(result) using the value returned from this block as the result.

    If the target is completed with a .Fail, then the returned future will also complete with .Fail and this block will not be executed.

    If the target is completed with a .Cancelled, then the returned future will also complete with .Cancelled and this block will not be executed.

    Warning - as of swift 1.2/2.0, you can’t use this method with a Future (it will give a compiler error). Instead use onAnySuccess()

    Declaration

    Swift

    public final func onSuccess<__Type>(executor : Executor = .Primary,
            block:(T) throws -> __Type) -> Future<__Type>

    Parameters

    executor

    an Executor to use to execute the block when it is ready to run.

    block

    a block takes the .Success result of the target Future and returns a new result.

    Return Value

    a new Future of type Future<__Type>

  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Declaration

    Swift

    public final func getCancelToken() -> CancellationToken
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol
  • Undocumented

    Declaration

    Swift

    public class Future<T> : FutureProtocol