TaskProtocol Protocol Reference

Success
A type that represents the success of some asynchronous work.
Declaration
Swift

associatedtype Success where Self.Success == Self.Value.Right
Failure
A type that represents the failure of some asynchronous work.
Declaration
Swift

typealias Failure = Error


                    
                    
                    uponSuccess(on:execute:)

Default implementation

Call some body closure if the task successfully completes.

Seealso

FutureProtocol.upon(_:execute:)

Default Implementation

Call some body closure if the task successfully completes.

Seealso

TaskProtocol.uponSuccess(on:execute:)

See

FutureProtocol.upon(_:execute:)

Declaration

Swift

func uponSuccess(on executor: Executor, execute body: @escaping(_ value: Success) -> Void)

Parameters

`executor`	A context for handling the `body`.
`body`	A closure to be invoked when the result is determined.
`value`	The determined success value.


                    
                    
                    uponFailure(on:execute:)

Default implementation

Call some body closure if the task fails.

Seealso

FutureProtocol.upon(_:execute:)

Default Implementation

Call some body closure if the task fails.

Seealso

TaskProtocol.uponFailure(on:execute:)

Seealso

FutureProtocol.upon(_:execute:)

Declaration

Swift

func uponFailure(on executor: Executor, execute body: @escaping(_ error: Failure) -> Void)

Parameters

`executor`	A context for handling the `body`.
`body`	A closure to be invoked when the result is determined.
`error`	The determined failure value.

isCancelled Default implementation
Tests whether the underlying work has been cancelled.

An implementation should be a best effort. By default, no cancellation is supported, and thus cannot become cancelled.

Should an implementation choose to be cancellable, it should fully implement cancellability with cancel.

Default Implementation
Declaration
Swift

var isCancelled: Bool { get }
cancel() Default implementation
Attempt to cancel the underlying work.

An implementation should be a best effort. By default, no cancellation is supported, and this method does nothing.

There are several situations in which a valid implementation may not actually cancel:
- The work has already completed.
- The work has entered an uncancelable state.
- An underlying task is not cancellable.
Should an implementation choose to be cancellable, it should fully implement cancellability with isCancelled.
Default Implementation
Declaration
Swift

func cancel()

andThen(upon:start:) Extension method
Begins another task by passing the result of the task to startNextTask once it completes successfully.

On Apple platforms, chaining a task contributes a unit of progress to the root task. A root task is the earliest task in a chain of tasks. If startNextTask runs and returns a task that itself reports progress, that progress will also contribute to the chain’s overall progress.

Cancelling the resulting task will attempt to cancel both the receiving task and the created task.
Declaration
Swift

public func andThen<NewTask: TaskProtocol>(upon executor: PreferredExecutor, start startNextTask: @escaping(Success) throws -> NewTask) -> Task<NewTask.Success>
andThen(upon:start:) Extension method
Begins another task by passing the result of the task to startNextTask once it completes successfully.

On Apple platforms, chaining a task contributes a unit of progress to the root task. A root task is the earliest task in a chain of tasks. If startNextTask runs and returns a task that itself reports progress, that progress will also contribute to the chain’s overall progress.

Cancelling the resulting task will attempt to cancel both the receiving task and the created task.

Note
It is important to keep in mind the thread safety of the startNextTask closure. andThen submits startNextTask to executor once the task completes successfully.

See
FutureProtocol.andThen(upon:start:)
Declaration
Swift

public func andThen<NewTask: TaskProtocol>(upon executor: Executor, start startNextTask: @escaping(Success) throws -> NewTask) -> Task<NewTask.Success>

fallback(upon:to:) Extension method
Begins another task in the case of the failure of self by calling restartTask with the error.

On Apple platforms, retrying a task contributes a unit of progress to the root task. A root task is the earliest task in a chain of tasks. If restartTask runs and returns a task that itself reports progress, that progress will also contribute to the chain’s overall progress.

Cancelling the resulting task will attempt to cancel both the receiving task and the created task.
Declaration
Swift

public func fallback<NewTask: TaskProtocol>(upon executor: PreferredExecutor, to restartTask: @escaping(Failure) throws -> NewTask) -> Task<Success> where NewTask.Success == Success
fallback(upon:to:) Extension method
Begins another task in the case of the failure of self by calling restartTask with the error.

On Apple platforms, retrying a task contributes a unit of progress to the root task. A root task is the earliest task in a chain of tasks. If restartTask runs and returns a task that itself reports progress, that progress will also contribute to the chain’s overall progress.

Cancelling the resulting task will attempt to cancel both the receiving task and the created task.

Note
It is important to keep in mind the thread safety of the restartTask closure. fallback submits restartTask to executor once the task fails.

See
FutureProtocol.andThen(upon:start:)
Declaration
Swift

public func fallback<NewTask: TaskProtocol>(upon executor: Executor, to restartTask: @escaping(Failure) throws -> NewTask) -> Task<Success> where NewTask.Success == Success


                    
                    
                    repeat(upon:count:continuingIf:to:)

Extension method

Begin a task immediately by calling startTask, then if it fails retry up to the numberOfAttempts.

Declaration

Swift

public static func `repeat`(
    upon preferredExecutor: PreferredExecutor,
    count numberOfAttempts: Int = 3,
    continuingIf shouldRetry: @escaping(Failure) -> Bool = { _ in return true },
    to startTask: @escaping() throws -> Task<Success>
) -> Task<Success>

repeat(upon:count:continuingIf:to:) Extension method
Begin a task immediately by calling startTask, then if it fails retry by calling startTask up to the numberOfAttempts.

If numberOfAttempts is less than 1, startTask will still be invoked regardless.

If provided, shouldRetry will be submitted to the executor to check whether the work can be retried for a given failure. Without a retry predicate, the attempt will always continue.

Note
It is important to keep in mind the thread safety of the startTask closure. It is initially called in the current execution context, then submitted to executor for any failures.
Declaration
Swift

public static func `repeat`( upon executor: Executor, count numberOfAttempts: Int = 3, continuingIf shouldRetry: @escaping(Failure) -> Bool = { _ in return true }, to startTask: @escaping() throws -> Task<Success> ) -> Task<Success>

ignored() Extension method
Returns a task that ignores the successful completion of this task.

This is semantically identical to the following:
```
myTask.map { _ in }
```
But behaves more efficiently.

The resulting task is cancellable in the same way the receiving task is.

See
map(transform:)
Declaration
Swift

public func ignored() -> Task<Void>

map(upon:transform:) Extension method
Returns a Task containing the result of mapping transform over the successful task’s value.

On Apple platforms, mapping a task reports its progress to the root task. A root task is the earliest task in a chain of tasks. During execution of transform, an additional progress object created using the current parent will also contribute to the chain’s progress.

The resulting task is cancellable in the same way the receiving task is.
Declaration
Swift

public func map<NewSuccess>(upon queue: PreferredExecutor, transform: @escaping(Success) throws -> NewSuccess) -> Task<NewSuccess>
map(upon:transform:) Extension method
Returns a Task containing the result of mapping transform over the successful task’s value.

The transform is submitted to the executor once the task completes.

On Apple platforms, mapping a task reports its progress to the root task. A root task is the earliest task in a chain of tasks. During execution of transform, an additional progress object created using the current parent will also contribute to the chain’s progress.

The resulting task is cancellable in the same way the receiving task is.

See
FutureProtocol.map(upon:transform:)
Declaration
Swift

public func map<NewSuccess>(upon executor: Executor, transform: @escaping(Success) throws -> NewSuccess) -> Task<NewSuccess>

succeed(with:) Extension method
Completes the task with a successful value, or a thrown error.

If value represents an expression that may fail by throwing, the task will implicitly catch the failure as the result.

Fulfilling this deferred value should usually be attempted only once.

Seealso
PromiseProtocol.fill(with:)
Declaration
Swift

@discardableResult public func succeed(with value: @autoclosure() throws -> Success) -> Bool
fail(with:) Extension method
Completes the task with a failed error.

See
fill(with:)
Declaration
Swift

@discardableResult public func fail(with error: Failure) -> Bool

succeed() Extension method
Completes the task with a success.

Fulfilling this deferred value should usually be attempted only once.

Seealso
PromiseProtocol.fill(with:)

Seealso
TaskProtocol.succeed(with:)
Declaration
Swift

@discardableResult public func succeed() -> Bool

recover(upon:substituting:) Extension method
Returns a Task containing the result of mapping substitution over the failed task’s error.

On Apple platforms, recovering from a failed task reports its progress to the root task. A root task is the earliest task in a chain of tasks. During execution of transform, an additional progress object created using the current parent will also contribute to the chain’s progress.

The resulting task is cancellable in the same way the receiving task is.
Declaration
Swift

public func recover(upon executor: PreferredExecutor, substituting substitution: @escaping(Failure) throws -> Success) -> Task<Success>
recover(upon:substituting:) Extension method
Returns a Task containing the result of mapping substitution over the failed task’s error.

recover submits the substitution to the executor once the task fails.

On Apple platforms, recovering from a failed task reports its progress to the root task. A root task is the earliest task in a chain of tasks. During execution of transform, an additional progress object created using the current parent will also contribute to the chain’s progress.

The resulting task is cancellable in the same way the receiving task is.

See
FutureProtocol.map(upon:transform:)
Declaration
Swift

public func recover(upon executor: Executor, substituting substitution: @escaping(Failure) throws -> Success) -> Task<Success>