This manual page is for Mac OS X version 10.6

Reading manual pages

dispatch_api(3)                         BSD Library Functions Manual                         dispatch_api(3)

NAME
     dispatch_api -- Designing API using dispatch

DESCRIPTION
     The following is a brief summary of some of the common design patterns to consider when designing and
     implementing API in terms of dispatch queues and blocks.

     A general recommendation is to allow both a callback block and target dispatch queue to be specified.
     This gives the application the greatest flexibility in handling asynchronous events.

     It's also recommended that interfaces take only a single block as the last parameter. This is both for
     consistency across projects, as well as the visual aesthetics of multiline blocks that are declared
     inline. The dispatch queue to which the block will be submitted should immediately precede the block
     argument (second-to-last argument). For example:

           read_async(file, callback_queue, ^{
                   printf("received callback.0);
           });

     When function pointer alternatives to interfaces that take blocks are provided, the argument order of
     the function signature should be identical to the block variant; with the exception that the block
     argument is replaced with a context pointer, and a new last parameter is added, which is the function
     to call.

     The function based callback should pass the context pointer as the first argument, and the subsequent
     arguments should be identical to the block based variant (albeit offset by one in order).

     It is also important to use consistent naming. The dispatch API, for example, uses the suffix "_f" for
     function based variants.

SEE ALSO
     dispatch(3), dispatch_async(3), dispatch_queue_create(3)

Darwin                                           May 1, 2009                                          Darwin