How does a completion handler work on iOS?

Question

Im trying to understand completion handlers & blocks. I believe you can use blocks for many deep programming things without completion handlers, but I think i understand that completion handlers are based on blocks. (So basically completion handlers need blocks but not the other way around).

So I saw this code on the internet about the old twitter framework:

[twitterFeed performRequestWithHandler:^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) {
        if (!error) {
            self.successLabel.text = @"Tweeted Successfully";
            [self playTweetSound];
        } else {
            // Show alert
        }
        // Stop indicator 
        sharedApplication.networkActivityIndicatorVisible = NO;
    }];

Here we are calling a method which does stuff (performs TWRequest) and returns when finished with responseData & urlResponse & error. Only when it returns does it execute the block which tests granted and stops the activity indicator. PERFECT!

Now this is a setup I have for a different app which works, but I'm trying to put the pieces together:

@interface
Define an ivar
typedef void (^Handler)(NSArray *users);
Declare the method
+(void)fetchUsersWithCompletionHandler:(Handler)handler;

@implementation
+(void)fetchUsersWithCompletionHandler:(Handler)handler {
    //...Code to create NSURLRequest omitted...
    __block NSArray *usersArray = [[NSArray alloc] init];

    //A. Executes the request 
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_BACKGROUND, 0), ^{

        // Peform the request
        NSURLResponse *response;
        NSError *error = nil;
        NSData *receivedData = [NSURLConnection sendSynchronousRequest:request
                                                     returningResponse:&response
                                                                 error:&error];
        // Deal with your error
        if (error) {
            }
            NSLog(@"Error %@", error);
            return;
        }
        // Else deal with data
        NSString *responseString = [[NSString alloc] initWithData:receivedData encoding:NSUTF8StringEncoding];
        usersArray = [NSJSONSerialization JSONObjectWithData:[responseString dataUsingEncoding:NSASCIIStringEncoding] options:0 error:nil];

        // Checks for handler & returns usersArray to main thread - but where does handler come from & how does it know to wait tip usersArray is populated?
        if (handler){
            dispatch_sync(dispatch_get_main_queue(), ^{
            handler(usersArray);
            });
        }
    });
}

Here is my understanding:

1. fetchUsersWithCompletionHandler is obviously the homologue of performRequestWithHandler
2. unfortunately this is a little more complex because there is a GCD call in the way...

But basically, the request is executed and the error is dealt with, the data is dealt with and then, the handler is checked. My question is, how does this handler part work? I understand if it exists then it will send back to the main queue and return the usersArray. But how does it know to wait until usersArray is populated? I guess whats confusing me is that fact that the method:block in this case has another block inside of it, the dispatch_async call. I guess what Im looking for is the logic that actually does stuff and knows WHEN to return the responseData and urlResponse. I know its not the same app, but I cant see the code for performRequestWithHandler.

Answer 1

Basically in this case it works like that:

1. You call fetchUsersWithCompletionHandler: from whatever thread you like (probably form main one).
2. It initializes NSURLRequest, then calls: dispatch_async(dispatch_get_global_queue... which basically creates block, and schedules it for processing on a background queue.

3. Since it is dispath_async, current thread leaves the fetchUsersWithCompletionHandler: method.

   ...
   time passes, till background queue has some free resources
   ...

4. And now, when the background queue is free, it consumes scheduled operation (Note: It performs synchronous request - so it waits for data):

   NSURLResponse *response;
   NSError *error = nil;
   NSData *receivedData = [NSURLConnection sendSynchronousRequest:request
                                                returningResponse:&response
                                                            error:&error];
   ...
   

5. Once data comes, then the usersArray is populated.

6. Code continues to this part:

   if (handler){
       dispatch_sync(dispatch_get_main_queue(), ^{
           handler(usersArray);
       });
   }
   

7. Now, if we have handler specified, it schedules block for invocation on a main queue. It is dispatch_sync, so execution on current thread won't proceed till main thread will be done with the block. At this point, background thread patiently waits.

   ...
   another moment passes
   ...

8. Now main queue has some free resources, so it consumes above block, and executes this code (passing previously populated usersArray to the 'handler'):

   handler(usersArray);
   

9. Once it is done, it returns from the block and continues consuming whatever it is in the main queue.

10. Since main thread is done with the block, also background thread (stuck at dispatch_sync) can proceed further. In this case it simply returns from block.

---

Edit: As for the questions you asked:

1. It's not like main/background queue will be always busy, it's just it may be. (assuming background queue does not support concurrent operations like the main one). Imagine following code, that is being executed on a main thread:

       dispatch_async(dispatch_get_main_queue(), ^{
           //here task #1 that takes 10 seconds to run
           NSLog(@"Task #1 finished");
       });
       NSLog(@"Task #1 scheduled");
   
       dispatch_async(dispatch_get_main_queue(), ^{
           //here task #2 that takes 5s to run
           NSLog(@"Task #2 finished");
       });
       NSLog(@"Task #2 scheduled");
   

Since both are dispatch_async calls, you schedule these for execution one after another. But task #2 won't be processed by main queue immediately, since first it has to leave current execution loop, secondly, it has to first finish task #1.

So the log output will be like that:

Task #1 scheduled
Task #2 scheduled
Task #1 finished
Task #2 finished

2.You have:

typedef void (^Handler)(NSArray *users);

Which declares block typedefe'd as Handler that has void return type and that accepts NSArray * as parameter.

Later, you have your function:

+(void)fetchUsersWithCompletionHandler:(Handler)handler

Which takes as a parameter block of type Handler and allow access to it using local name handler.

And step #8:

handler(usersArray);

Which just directly calls handler block (like you were calling any C/C++ function) and passes usersArray as a parameter to it.