| commit | author | age | ||
| bad748 | 1 | /* |
| W | 2 | * Copyright (c) 2014, Facebook, Inc. |
| 3 | * All rights reserved. | |
| 4 | * | |
| 5 | * This source code is licensed under the BSD-style license found in the | |
| 6 | * LICENSE file in the root directory of this source tree. An additional grant | |
| 7 | * of patent rights can be found in the PATENTS file in the same directory. | |
| 8 | * | |
| 9 | */ | |
| 10 | ||
| 11 | #import <Foundation/Foundation.h> | |
| 12 | ||
| 13 | #import <Bolts/BFCancellationToken.h> | |
| 13e53a | 14 | #import <Bolts/BFGeneric.h> |
| bad748 | 15 | |
| W | 16 | NS_ASSUME_NONNULL_BEGIN |
| 17 | ||
| 18 | /*! | |
| 19 | Error domain used if there was multiple errors on <BFTask taskForCompletionOfAllTasks:>. | |
| 20 | */ | |
| 21 | extern NSString *const BFTaskErrorDomain; | |
| 22 | ||
| 23 | /*! | |
| 24 | An error code used for <BFTask taskForCompletionOfAllTasks:>, if there were multiple errors. | |
| 25 | */ | |
| 26 | extern NSInteger const kBFMultipleErrorsError; | |
| 27 | ||
| 28 | /*! | |
| 29 | An error userInfo key used if there were multiple errors on <BFTask taskForCompletionOfAllTasks:>. | |
| 30 | Value type is `NSArray<NSError *> *`. | |
| 31 | */ | |
| 32 | extern NSString *const BFTaskMultipleErrorsUserInfoKey; | |
| 33 | ||
| 34 | @class BFExecutor; | |
| 35 | @class BFTask; | |
| 36 | ||
| 37 | /*! | |
| 38 | The consumer view of a Task. A BFTask has methods to | |
| 39 | inspect the state of the task, and to add continuations to | |
| 40 | be run once the task is complete. | |
| 41 | */ | |
| 42 | @interface BFTask<__covariant ResultType> : NSObject | |
| 43 | ||
| 44 | /*! | |
| 45 | A block that can act as a continuation for a task. | |
| 46 | */ | |
| 9febd9 | 47 | typedef __nullable id(^BFContinuationBlock)(BFTask<ResultType> *t); |
| bad748 | 48 | |
| W | 49 | /*! |
| 50 | Creates a task that is already completed with the given result. | |
| 51 | @param result The result for the task. | |
| 52 | */ | |
| 53 | + (instancetype)taskWithResult:(nullable ResultType)result; | |
| 54 | ||
| 55 | /*! | |
| 56 | Creates a task that is already completed with the given error. | |
| 57 | @param error The error for the task. | |
| 58 | */ | |
| 59 | + (instancetype)taskWithError:(NSError *)error; | |
| 60 | ||
| 61 | /*! | |
| 62 | Creates a task that is already cancelled. | |
| 63 | */ | |
| 64 | + (instancetype)cancelledTask; | |
| 65 | ||
| 66 | /*! | |
| 67 | Returns a task that will be completed (with result == nil) once | |
| 68 | all of the input tasks have completed. | |
| 69 | @param tasks An `NSArray` of the tasks to use as an input. | |
| 70 | */ | |
| 71 | + (instancetype)taskForCompletionOfAllTasks:(nullable NSArray<BFTask *> *)tasks; | |
| 72 | ||
| 73 | /*! | |
| 74 | Returns a task that will be completed once all of the input tasks have completed. | |
| 75 | If all tasks complete successfully without being faulted or cancelled the result will be | |
| 76 | an `NSArray` of all task results in the order they were provided. | |
| 77 | @param tasks An `NSArray` of the tasks to use as an input. | |
| 78 | */ | |
| 79 | + (instancetype)taskForCompletionOfAllTasksWithResults:(nullable NSArray<BFTask *> *)tasks; | |
| 80 | ||
| 81 | /*! | |
| 82 | Returns a task that will be completed once there is at least one successful task. | |
| 13e53a | 83 | The first task to successuly complete will set the result, all other tasks results are |
| bad748 | 84 | ignored. |
| W | 85 | @param tasks An `NSArray` of the tasks to use as an input. |
| 86 | */ | |
| 87 | + (instancetype)taskForCompletionOfAnyTask:(nullable NSArray<BFTask *> *)tasks; | |
| 88 | ||
| 89 | /*! | |
| 90 | Returns a task that will be completed a certain amount of time in the future. | |
| 91 | @param millis The approximate number of milliseconds to wait before the | |
| 92 | task will be finished (with result == nil). | |
| 93 | */ | |
| 13e53a | 94 | + (BFTask<BFVoid> *)taskWithDelay:(int)millis; |
| bad748 | 95 | |
| W | 96 | /*! |
| 97 | Returns a task that will be completed a certain amount of time in the future. | |
| 98 | @param millis The approximate number of milliseconds to wait before the | |
| 99 | task will be finished (with result == nil). | |
| 100 | @param token The cancellation token (optional). | |
| 101 | */ | |
| 13e53a | 102 | + (BFTask<BFVoid> *)taskWithDelay:(int)millis cancellationToken:(nullable BFCancellationToken *)token; |
| bad748 | 103 | |
| W | 104 | /*! |
| 105 | Returns a task that will be completed after the given block completes with | |
| 106 | the specified executor. | |
| 107 | @param executor A BFExecutor responsible for determining how the | |
| 108 | continuation block will be run. | |
| 109 | @param block The block to immediately schedule to run with the given executor. | |
| 110 | @returns A task that will be completed after block has run. | |
| 111 | If block returns a BFTask, then the task returned from | |
| 112 | this method will not be completed until that task is completed. | |
| 113 | */ | |
| 13e53a | 114 | + (instancetype)taskFromExecutor:(BFExecutor *)executor withBlock:(nullable id (^)(void))block; |
| bad748 | 115 | |
| W | 116 | // Properties that will be set on the task once it is completed. |
| 117 | ||
| 118 | /*! | |
| 119 | The result of a successful task. | |
| 120 | */ | |
| 121 | @property (nullable, nonatomic, strong, readonly) ResultType result; | |
| 122 | ||
| 123 | /*! | |
| 124 | The error of a failed task. | |
| 125 | */ | |
| 126 | @property (nullable, nonatomic, strong, readonly) NSError *error; | |
| 127 | ||
| 128 | /*! | |
| 129 | Whether this task has been cancelled. | |
| 130 | */ | |
| 131 | @property (nonatomic, assign, readonly, getter=isCancelled) BOOL cancelled; | |
| 132 | ||
| 133 | /*! | |
| 13e53a | 134 | Whether this task has completed due to an error. |
| bad748 | 135 | */ |
| W | 136 | @property (nonatomic, assign, readonly, getter=isFaulted) BOOL faulted; |
| 137 | ||
| 138 | /*! | |
| 139 | Whether this task has completed. | |
| 140 | */ | |
| 141 | @property (nonatomic, assign, readonly, getter=isCompleted) BOOL completed; | |
| 142 | ||
| 143 | /*! | |
| 144 | Enqueues the given block to be run once this task is complete. | |
| 145 | This method uses a default execution strategy. The block will be | |
| 146 | run on the thread where the previous task completes, unless the | |
| 147 | the stack depth is too deep, in which case it will be run on a | |
| 148 | dispatch queue with default priority. | |
| 149 | @param block The block to be run once this task is complete. | |
| 150 | @returns A task that will be completed after block has run. | |
| 151 | If block returns a BFTask, then the task returned from | |
| 152 | this method will not be completed until that task is completed. | |
| 153 | */ | |
| 13e53a | 154 | - (BFTask *)continueWithBlock:(BFContinuationBlock)block NS_SWIFT_NAME(continueWith(block:)); |
| bad748 | 155 | |
| W | 156 | /*! |
| 157 | Enqueues the given block to be run once this task is complete. | |
| 158 | This method uses a default execution strategy. The block will be | |
| 159 | run on the thread where the previous task completes, unless the | |
| 160 | the stack depth is too deep, in which case it will be run on a | |
| 161 | dispatch queue with default priority. | |
| 162 | @param block The block to be run once this task is complete. | |
| 163 | @param cancellationToken The cancellation token (optional). | |
| 164 | @returns A task that will be completed after block has run. | |
| 165 | If block returns a BFTask, then the task returned from | |
| 166 | this method will not be completed until that task is completed. | |
| 167 | */ | |
| 13e53a | 168 | - (BFTask *)continueWithBlock:(BFContinuationBlock)block |
| H | 169 | cancellationToken:(nullable BFCancellationToken *)cancellationToken NS_SWIFT_NAME(continueWith(block:cancellationToken:)); |
| bad748 | 170 | |
| W | 171 | /*! |
| 172 | Enqueues the given block to be run once this task is complete. | |
| 173 | @param executor A BFExecutor responsible for determining how the | |
| 174 | continuation block will be run. | |
| 175 | @param block The block to be run once this task is complete. | |
| 176 | @returns A task that will be completed after block has run. | |
| 177 | If block returns a BFTask, then the task returned from | |
| 178 | this method will not be completed until that task is completed. | |
| 179 | */ | |
| 13e53a | 180 | - (BFTask *)continueWithExecutor:(BFExecutor *)executor |
| H | 181 | withBlock:(BFContinuationBlock)block NS_SWIFT_NAME(continueWith(executor:block:)); |
| 182 | ||
| bad748 | 183 | /*! |
| W | 184 | Enqueues the given block to be run once this task is complete. |
| 185 | @param executor A BFExecutor responsible for determining how the | |
| 186 | continuation block will be run. | |
| 187 | @param block The block to be run once this task is complete. | |
| 188 | @param cancellationToken The cancellation token (optional). | |
| 189 | @returns A task that will be completed after block has run. | |
| 190 | If block returns a BFTask, then the task returned from | |
| 191 | his method will not be completed until that task is completed. | |
| 192 | */ | |
| 193 | - (BFTask *)continueWithExecutor:(BFExecutor *)executor | |
| 194 | block:(BFContinuationBlock)block | |
| 13e53a | 195 | cancellationToken:(nullable BFCancellationToken *)cancellationToken |
| H | 196 | NS_SWIFT_NAME(continueWith(executor:block:cancellationToken:)); |
| bad748 | 197 | |
| W | 198 | /*! |
| 199 | Identical to continueWithBlock:, except that the block is only run | |
| 13e53a | 200 | if this task did not produce a cancellation or an error. |
| bad748 | 201 | If it did, then the failure will be propagated to the returned |
| W | 202 | task. |
| 203 | @param block The block to be run once this task is complete. | |
| 204 | @returns A task that will be completed after block has run. | |
| 205 | If block returns a BFTask, then the task returned from | |
| 206 | this method will not be completed until that task is completed. | |
| 207 | */ | |
| 13e53a | 208 | - (BFTask *)continueWithSuccessBlock:(BFContinuationBlock)block NS_SWIFT_NAME(continueOnSuccessWith(block:)); |
| bad748 | 209 | |
| W | 210 | /*! |
| 211 | Identical to continueWithBlock:, except that the block is only run | |
| 13e53a | 212 | if this task did not produce a cancellation or an error. |
| bad748 | 213 | If it did, then the failure will be propagated to the returned |
| W | 214 | task. |
| 215 | @param block The block to be run once this task is complete. | |
| 216 | @param cancellationToken The cancellation token (optional). | |
| 217 | @returns A task that will be completed after block has run. | |
| 218 | If block returns a BFTask, then the task returned from | |
| 219 | this method will not be completed until that task is completed. | |
| 220 | */ | |
| 13e53a | 221 | - (BFTask *)continueWithSuccessBlock:(BFContinuationBlock)block |
| H | 222 | cancellationToken:(nullable BFCancellationToken *)cancellationToken |
| 223 | NS_SWIFT_NAME(continueOnSuccessWith(block:cancellationToken:)); | |
| bad748 | 224 | |
| W | 225 | /*! |
| 226 | Identical to continueWithExecutor:withBlock:, except that the block | |
| 13e53a | 227 | is only run if this task did not produce a cancellation, error, or an error. |
| H | 228 | If it did, then the failure will be propagated to the returned task. |
| bad748 | 229 | @param executor A BFExecutor responsible for determining how the |
| W | 230 | continuation block will be run. |
| 231 | @param block The block to be run once this task is complete. | |
| 232 | @returns A task that will be completed after block has run. | |
| 233 | If block returns a BFTask, then the task returned from | |
| 234 | this method will not be completed until that task is completed. | |
| 235 | */ | |
| 13e53a | 236 | - (BFTask *)continueWithExecutor:(BFExecutor *)executor |
| H | 237 | withSuccessBlock:(BFContinuationBlock)block NS_SWIFT_NAME(continueOnSuccessWith(executor:block:)); |
| bad748 | 238 | |
| W | 239 | /*! |
| 240 | Identical to continueWithExecutor:withBlock:, except that the block | |
| 13e53a | 241 | is only run if this task did not produce a cancellation or an error. |
| H | 242 | If it did, then the failure will be propagated to the returned task. |
| bad748 | 243 | @param executor A BFExecutor responsible for determining how the |
| W | 244 | continuation block will be run. |
| 245 | @param block The block to be run once this task is complete. | |
| 246 | @param cancellationToken The cancellation token (optional). | |
| 247 | @returns A task that will be completed after block has run. | |
| 248 | If block returns a BFTask, then the task returned from | |
| 249 | this method will not be completed until that task is completed. | |
| 250 | */ | |
| 251 | - (BFTask *)continueWithExecutor:(BFExecutor *)executor | |
| 252 | successBlock:(BFContinuationBlock)block | |
| 13e53a | 253 | cancellationToken:(nullable BFCancellationToken *)cancellationToken |
| H | 254 | NS_SWIFT_NAME(continueOnSuccessWith(executor:block:cancellationToken:)); |
| bad748 | 255 | |
| W | 256 | /*! |
| 257 | Waits until this operation is completed. | |
| 258 | This method is inefficient and consumes a thread resource while | |
| 259 | it's running. It should be avoided. This method logs a warning | |
| 260 | message if it is used on the main thread. | |
| 261 | */ | |
| 262 | - (void)waitUntilFinished; | |
| 263 | ||
| 264 | @end | |
| 265 | ||
| 266 | NS_ASSUME_NONNULL_END | |
