dispatch_api(3)

🌸 NAME 🌸

okay so you're looking at dispatch_api(3), bestie — it's the Designing API using dispatch page, and it lives in the Library Functions Manual. If you're building stuff with dispatch queues and blocks, this is your moment. 💅

✨ DESCRIPTION ✨

Here's the tea, fr fr: this is a brief summary of some of the common design patterns to keep in mind when you're designing and implementing API in terms of dispatch queues and blocks. Not me making architecture cute AND correct 😌

• A general recommendation is to let peeps specify both a callback block and a target dispatch queue. That gives the application the greatest flexibility in handling asynchronous events. Slay.
• Also recommended: interfaces should take only a single block as the last parameter. Why? For consistency across projects, and honestly for the visual aesthetics of multiline blocks that are declared inline. It's giving clean code, periodt.
• The dispatch queue that the block will be submitted to should come immediately before the block argument, i.e. it's the second-to-last argument. Example time:

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

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. iykyk ✨

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). No cap.

Also: use consistent naming. The dispatch API, for example, uses the suffix _f for function based variants. Consistency ate and left no crumbs. 🍓

💖 SEE ALSO 💖

• dispatch(3)
• dispatch_async(3)
• dispatch_queue_create(3)

And finally, this whole page is from Darwin, May 1, 2009, and it's literally dispatch_api(3). Bye bestie, go design something iconic. 💜🦋