Sin descripción

AWSTask.h 10KB

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