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