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

NAME

4     dispatch_api — Designing API using dispatch
5

DESCRIPTION

7     The following is a brief summary of some of the common design patterns to
8     consider when designing and implementing API in terms of dispatch queues
9     and blocks.
10
11     A general recommendation is to allow both a callback block and target
12     dispatch queue to be specified. This gives the application the greatest
13     flexibility in handling asynchronous events.
14
15     It's also recommended that interfaces take only a single block as the
16     last parameter. This is both for consistency across projects, as well as
17     the visual aesthetics of multiline blocks that are declared inline. The
18     dispatch queue to which the block will be submitted should immediately
19     precede the block argument (second-to-last argument). For example:
20
21           read_async(file, callback_queue, ^{
22                   printf("received callback.\n");
23           });
24
25     When function pointer alternatives to interfaces that take blocks are
26     provided, the argument order of the function signature should be identi‐
27     cal to the block variant; with the exception that the block argument is
28     replaced with a context pointer, and a new last parameter is added, which
29     is the function to call.
30
31     The function based callback should pass the context pointer as the first
32     argument, and the subsequent arguments should be identical to the block
33     based variant (albeit offset by one in order).
34
35     It is also important to use consistent naming. The dispatch API, for
36     example, uses the suffix "_f" for function based variants.
37

SEE ALSO

39     dispatch(3), dispatch_async(3), dispatch_queue_create(3)
40
41Darwin                            May 1, 2009                           Darwin
Impressum