Adds race task

Bolts/Common/BFTask.h

@@ -82,6 +82,14 @@ typedef __nullable id(^BFContinuationBlock)(BFTask<ResultType> *task);
  */
 + (instancetype)taskForCompletionOfAllTasksWithResults:(nullable NSArray<BFTask *> *)tasks;
 
+/*!
+ Returns a task that will be completed once there is at least one successful task.
+ The first task to successuly complete will set the result, all other tasks results are 
+ ignored.
+ @param tasks An `NSArray` of the tasks to use as an input.
+ */
++ (instancetype)taskForCompletionOfAnyTask:(nullable NSArray<BFTask *> *)tasks;
+
 /*!
  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

Bolts/Common/BFTask.m

@@ -174,6 +174,72 @@ + (instancetype)taskForCompletionOfAllTasksWithResults:(nullable NSArray<BFTask
     }];
 }
 
++ (instancetype)taskForCompletionOfAnyTask:(nullable NSArray<BFTask *> *)tasks
+{
+    __block int32_t total = (int32_t)tasks.count;
+    if (total == 0) {
+        return [self taskWithResult:nil];
+    }
+
+    __block int completed = 0;
+    __block int32_t cancelled = 0;
+
+    NSObject *lock = [NSObject new];
+    NSMutableArray<NSError *> *errors = [NSMutableArray new];
+    NSMutableArray<NSException *> *exceptions = [NSMutableArray new];
+
+    BFTaskCompletionSource *source = [BFTaskCompletionSource taskCompletionSource];
+    for (BFTask *task in tasks) {
+        [task continueWithBlock:^id(BFTask *task) {
+            if (task.exception != nil) {
+                @synchronized(lock) {
+                    [exceptions addObject:task.exception];
+                }
+            } else if (task.error != nil) {
+                @synchronized(lock) {
+                    [errors addObject:task.error];
+                }
+            } else if (task.cancelled) {
+                OSAtomicIncrement32Barrier(&cancelled);
+            } else {
+                if(OSAtomicCompareAndSwap32Barrier(0, 1, &completed)) {
+                    [source setResult:task.result];
+                }
+            }
+
+            if (OSAtomicDecrement32Barrier(&total) == 0 &&
+                OSAtomicCompareAndSwap32Barrier(0, 1, &completed)) {
+                if (cancelled > 0) {
+                    [source cancel];
+                } else if (exceptions.count > 0) {
+                    if (exceptions.count == 1) {
+                        source.exception = exceptions.firstObject;
+                    } else {
+                        NSException *exception =
+                        [NSException exceptionWithName:BFTaskMultipleExceptionsException
+                                                reason:@"There were multiple exceptions."
+                                              userInfo:@{ @"exceptions": exceptions }];
+                        source.exception = exception;
+                    }
+                } else if (errors.count > 0) {
+                    if (errors.count == 1) {
+                        source.error = errors.firstObject;
+                    } else {
+                        NSError *error = [NSError errorWithDomain:BFTaskErrorDomain
+                                                             code:kBFMultipleErrorsError
+                                                         userInfo:@{ @"errors": errors }];
+                        source.error = error;
+                    }
+                }
+            }
+            // Abort execution of per tasks continuations
+            return nil;
+        }];
+    }
+    return source.task;
+}
+
+
 + (instancetype)taskWithDelay:(int)millis {
     BFTaskCompletionSource *tcs = [BFTaskCompletionSource taskCompletionSource];
     dispatch_time_t popTime = dispatch_time(DISPATCH_TIME_NOW, millis * NSEC_PER_MSEC);

BoltsTests/TaskTests.m

@@ -618,6 +618,7 @@ - (void)testTaskForCompletionOfAllTasksSuccessError {
     XCTAssertTrue(allTasks.faulted, @"Task should be faulted");
 }
 
+
 - (void)testTaskForCompletionOfAllTasksWithResultsNoTasksImmediateCompletion {
     NSMutableArray *tasks = [NSMutableArray array];
 
@@ -628,6 +629,78 @@ - (void)testTaskForCompletionOfAllTasksWithResultsNoTasksImmediateCompletion {
     XCTAssertTrue(task.result != nil);
 }
 
+- (void)testTasksForTaskForCompletionOfAnyTasksWithSuccess {
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:@[[BFTask taskWithDelay:20], [BFTask taskWithResult:@"success"]]];
+    [task waitUntilFinished];
+
+    XCTAssertEqualObjects(@"success", task.result);
+}
+
+- (void)testTasksForTaskForCompletionOfAnyTasksWithRacing {
+    BFTask *first = [[BFTask taskWithDelay:2] continueWithBlock:^id _Nullable(BFTask * _Nonnull task) {
+        return [BFTask taskWithResult:@"first"];
+    }];
+    BFTask *second = [[BFTask taskWithDelay:3] continueWithBlock:^id _Nullable(BFTask * _Nonnull task) {
+        return [BFTask taskWithResult:@"second"];
+    }];
+
+
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:@[first, second]];
+    [task waitUntilFinished];
+
+    XCTAssertEqualObjects(@"first", task.result);
+}
+
+- (void)testTasksForTaskForCompletionOfAnyTasksWithErrorAndSuccess {
+    NSError *error = [NSError errorWithDomain:@"BoltsTests"
+                                         code:35
+                                     userInfo:nil];
+
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:@[[BFTask taskWithError:error], [BFTask taskWithResult:@"success"]]];
+    [task waitUntilFinished];
+
+    XCTAssertEqualObjects(@"success", task.result);
+    XCTAssertNil(task.error);
+}
+
+- (void)testTasksForTaskForCompletionOfAnyTasksWithError {
+    NSError *error = [NSError errorWithDomain:@"BoltsTests"
+                                         code:35
+                                     userInfo:nil];
+
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:@[[BFTask taskWithError:error]]];
+    [task waitUntilFinished];
+
+    XCTAssertEqualObjects(error, task.error);
+    XCTAssertNotNil(task.error);
+}
+
+- (void)testTasksForTaskForCompletionOfAnyTasksWithNilArray {
+
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:nil];
+    [task waitUntilFinished];
+
+    XCTAssertNil(task.result);
+    XCTAssertNil(task.error);
+    XCTAssertNil(task.exception);
+}
+
+- (void)testTasksForTaskForCompletionOfAnyTasksAllErrors {
+    NSError *error = [NSError errorWithDomain:@"BoltsTests"
+                                         code:35
+                                     userInfo:nil];
+
+    BFTask *task = [BFTask taskForCompletionOfAnyTask:@[[BFTask taskWithError:error], [BFTask taskWithError:error]]];
+    [task waitUntilFinished];
+
+    XCTAssertNil(task.result);
+    XCTAssertNotNil(task.error);
+    XCTAssertNotNil(task.error.userInfo);
+    XCTAssertEqualObjects(@"bolts", task.error.domain);
+    XCTAssertTrue([task.error.userInfo[@"errors"] isKindOfClass:[NSArray class]]);
+    XCTAssertEqual(2, [task.error.userInfo[@"errors"] count]);
+}
+
 - (void)testWaitUntilFinished {
     BFTask *task = [[BFTask taskWithDelay:50] continueWithBlock:^id(BFTask *task) {
         return @"foo";