AWSTask.swift

import UIKit

/*
 *  Copyright (c) 2014, Facebook, Inc.
 *  All rights reserved.
 *
 *  This source code is licensed under the BSD-style license found in the
 *  LICENSE file in the root directory of this source tree. An additional grant
 *  of patent rights can be found in the PATENTS file in the same directory.
 *
 */

/*!
 Error domain used if there was multiple errors on <AWSTask taskForCompletionOfAllTasks:>.
 */
public let AWSTaskErrorDomain: String

/*!
 An error code used for <AWSTask taskForCompletionOfAllTasks:>, if there were multiple errors.
 */
public let kAWSMultipleErrorsError: Int

/*!
 An exception that is thrown if there was multiple exceptions on <AWSTask taskForCompletionOfAllTasks:>.
 */
public let AWSTaskMultipleExceptionsException: String

/*!
 The consumer view of a Task. A AWSTask has methods to
 inspect the state of the task, and to add continuations to
 be run once the task is complete.
 */
open class AWSTask<ResultType : AnyObject> : NSObject {

    
    /*!
     A block that can act as a continuation for a task.
     */
    
    /*!
     Creates a task that is already completed with the given result.
     @param result The result for the task.
     */
    public convenience init(result: ResultType?)

    
    /*!
     Creates a task that is already completed with the given error.
     @param error The error for the task.
     */
    public convenience init(error: Error)

    
    /*!
     Creates a task that is already completed with the given exception.
     @param exception The exception for the task.
     */
    public convenience init(exception: NSException)

    
    /*!
     Creates a task that is already cancelled.
     */
    open class func cancelled() -> Self

    
    /*!
     Returns a task that will be completed (with result == nil) once
     all of the input tasks have completed.
     @param tasks An `NSArray` of the tasks to use as an input.
     */
    public convenience init(forCompletionOfAllTasks tasks: [AWSTask<AnyObject>]?)

    
    /*!
     Returns a task that will be completed once all of the input tasks have completed.
     If all tasks complete successfully without being faulted or cancelled the result will be
     an `NSArray` of all task results in the order they were provided.
     @param tasks An `NSArray` of the tasks to use as an input.
     */
    public convenience init(forCompletionOfAllTasksWithResults tasks: [AWSTask<AnyObject>]?)

    
    /*!
     Returns a task that will be completed a certain amount of time in the future.
     @param millis The approximate number of milliseconds to wait before the
     task will be finished (with result == nil).
     */
    public convenience init(delay millis: Int32)

    
    /*!
     Returns a task that will be completed a certain amount of time in the future.
     @param millis The approximate number of milliseconds to wait before the
     task will be finished (with result == nil).
     @param token The cancellation token (optional).
     */
    public convenience init(delay millis: Int32, cancellationToken token: AWSCancellationToken?)

    
    /*!
     Returns a task that will be completed after the given block completes with
     the specified executor.
     @param executor A AWSExecutor responsible for determining how the
     continuation block will be run.
     @param block The block to immediately schedule to run with the given executor.
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    public convenience init(from executor: AWSExecutor, with block: (() -> Any)? = nil)

    
    // Properties that will be set on the task once it is completed.
    
    /*!
     The result of a successful task.
     */
    open var result: ResultType? { get }

    
    /*!
     The error of a failed task.
     */
    open var error: Error? { get }

    
    /*!
     The exception of a failed task.
     */
    open var exception: NSException? { get }

    
    /*!
     Whether this task has been cancelled.
     */
    open var isCancelled: Bool { get }

    
    /*!
     Whether this task has completed due to an error or exception.
     */
    open var isFaulted: Bool { get }

    
    /*!
     Whether this task has completed.
     */
    open var isCompleted: Bool { get }

    
    /*!
     Enqueues the given block to be run once this task is complete.
     This method uses a default execution strategy. The block will be
     run on the thread where the previous task completes, unless the
     the stack depth is too deep, in which case it will be run on a
     dispatch queue with default priority.
     @param block The block to be run once this task is complete.
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(_ block: AWSCore.AWSContinuationBlock) -> AWSTask<AnyObject>

    
    /*!
     Enqueues the given block to be run once this task is complete.
     This method uses a default execution strategy. The block will be
     run on the thread where the previous task completes, unless the
     the stack depth is too deep, in which case it will be run on a
     dispatch queue with default priority.
     @param block The block to be run once this task is complete.
     @param cancellationToken The cancellation token (optional).
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(_ block: @escaping AWSCore.AWSContinuationBlock, cancellationToken: AWSCancellationToken?) -> AWSTask<AnyObject>

    
    /*!
     Enqueues the given block to be run once this task is complete.
     @param executor A AWSExecutor responsible for determining how the
     continuation block will be run.
     @param block The block to be run once this task is complete.
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(with executor: AWSExecutor, with block: @escaping AWSCore.AWSContinuationBlock) -> AWSTask<AnyObject>

    /*!
     Enqueues the given block to be run once this task is complete.
     @param executor A AWSExecutor responsible for determining how the
     continuation block will be run.
     @param block The block to be run once this task is complete.
     @param cancellationToken The cancellation token (optional).
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     his method will not be completed until that task is completed.
     */
    open func `continue`(with executor: AWSExecutor, block: @escaping AWSCore.AWSContinuationBlock, cancellationToken: AWSCancellationToken?) -> AWSTask<AnyObject>

    
    /*!
     Identical to continueWithBlock:, except that the block is only run
     if this task did not produce a cancellation, error, or exception.
     If it did, then the failure will be propagated to the returned
     task.
     @param block The block to be run once this task is complete.
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(successBlock block: @escaping AWSCore.AWSContinuationBlock) -> AWSTask<AnyObject>

    
    /*!
     Identical to continueWithBlock:, except that the block is only run
     if this task did not produce a cancellation, error, or exception.
     If it did, then the failure will be propagated to the returned
     task.
     @param block The block to be run once this task is complete.
     @param cancellationToken The cancellation token (optional).
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(successBlock block: @escaping AWSCore.AWSContinuationBlock, cancellationToken: AWSCancellationToken?) -> AWSTask<AnyObject>

    
    /*!
     Identical to continueWithExecutor:withBlock:, except that the block
     is only run if this task did not produce a cancellation, error, or
     exception. If it did, then the failure will be propagated to the
     returned task.
     @param executor A AWSExecutor responsible for determining how the
     continuation block will be run.
     @param block The block to be run once this task is complete.
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(with executor: AWSExecutor, withSuccessBlock block: @escaping AWSCore.AWSContinuationBlock) -> AWSTask<AnyObject>

    
    /*!
     Identical to continueWithExecutor:withBlock:, except that the block
     is only run if this task did not produce a cancellation, error, or
     exception. If it did, then the failure will be propagated to the
     returned task.
     @param executor A AWSExecutor responsible for determining how the
     continuation block will be run.
     @param block The block to be run once this task is complete.
     @param cancellationToken The cancellation token (optional).
     @returns A task that will be completed after block has run.
     If block returns a AWSTask, then the task returned from
     this method will not be completed until that task is completed.
     */
    open func `continue`(with executor: AWSExecutor, successBlock block: @escaping AWSCore.AWSContinuationBlock, cancellationToken: AWSCancellationToken?) -> AWSTask<AnyObject>

    
    /*!
     Waits until this operation is completed.
     This method is inefficient and consumes a thread resource while
     it's running. It should be avoided. This method logs a warning
     message if it is used on the main thread.
     */
    open func waitUntilFinished()
}
/*!
 A block that can act as a continuation for a task.
 */
public typealias AWSContinuationBlock = (AWSTask<ResultType>) -> Any?