dispatch_group_create(3)

💖 dispatch_group_create(3) — like, the group chat for your blocks 💖

Library Functions Manual ✨ bestie edition ✨

---

🌸 NAME 🌸

dispatch_group_create, dispatch_group_async, dispatch_group_wait, dispatch_group_notify — group blocks submitted to queues

okay so literally it's a way to herd a bunch of blocks into one lil squad and then be like "tell me when y'all are done". iconic behavior honestly.

---

🎀 SYNOPSIS 🎀

#include <dispatch/dispatch.h>

dispatch_group_t
dispatch_group_create(void);

void
dispatch_group_enter(dispatch_group_t group);

void
dispatch_group_leave(dispatch_group_t group);

long
dispatch_group_wait(dispatch_group_t group, dispatch_time_t timeout);

void
dispatch_group_notify(dispatch_group_t group, dispatch_queue_t queue,
    void (^block)(void));

void
dispatch_group_notify_f(dispatch_group_t group, dispatch_queue_t queue,
    void *context, void (*function)(void *));

void
dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue,
    void (^block)(void));

void
dispatch_group_async_f(dispatch_group_t group, dispatch_queue_t queue,
    void *context, void (*function)(void *));

---

🦋 DESCRIPTION 🦋

A dispatch group is an association of one or more blocks submitted to dispatch queues for asynchronous invocation. Basically: you round up a bunch of blocks, toss them at queues, and then the group keeps track of all of them for you. Applications may use dispatch groups to wait for the completion of blocks associated with the group. no cap, that's the whole point.

The dispatch_group_create() function returns a new and empty dispatch group. fresh out the box, zero blocks, main character energy ✨

The dispatch_group_enter() and dispatch_group_leave() functions update the number of blocks running within a group. every enter is a lil +1, every leave is a lil -1, and the group is doing math in the background like it's keeping score 🧮

The dispatch_group_wait() function waits until all blocks associated with the group have completed, or until the specified timeout has elapsed. If the group becomes empty within the specified amount of time, the function will return zero indicating success. Otherwise, a non-zero return code will be returned. When DISPATCH_TIME_FOREVER is passed as the timeout, calls to this function will wait an unlimited amount of time until the group becomes empty and the return value is always zero. so like, it will literally never give up on you bestie, it's ride or die 🫶

The dispatch_group_notify() function provides asynchronous notification of the completion of the blocks associated with the group by submitting the block to the specified queue once all blocks associated with the group have completed. The system holds a reference to the dispatch group while an asynchronous notification is pending, therefore it is valid to release the group after setting a notification block. The group will be empty at the time the notification block is submitted to the target queue. The group may either be released with dispatch_release() or reused for additional operations. so you can yeet it or recycle it, your call 💅

The dispatch_group_async() convenience function behaves like so:

void
dispatch_group_async(dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block)
{
    dispatch_retain(group);
    dispatch_group_enter(group);
    dispatch_async(queue, ^{
        block();
        dispatch_group_leave(group);
        dispatch_release(group);
    });
}

see?? it's just doing retain + enter + async + leave + release for you so you don't have to. it's giving personal assistant 🎀

---

⭐ RETURN VALUE ⭐

The dispatch_group_create() function returns NULL on failure and non-NULL on success. so if you get NULL, that's a vibe check failed, sorry 😭

The dispatch_group_wait() function returns zero upon success and non-zero after the timeout expires. If the timeout is DISPATCH_TIME_FOREVER, then dispatch_group_wait() waits forever and always returns zero. periodt.

---

💜 MEMORY MODEL 💜

Dispatch groups are retained and released via calls to dispatch_retain() and dispatch_release(). keep that reference count balanced bestie, no leaks in this house 🧚

---

🌈 FUNDAMENTALS 🌈

The dispatch_group_async() and dispatch_group_notify() functions are wrappers around dispatch_group_async_f() and dispatch_group_notify_f() respectively. iykyk — the _f versions are the real ones underneath 🫡

---

👑 SEE ALSO 👑

• dispatch(3)
• dispatch_async(3)
• dispatch_object(3)
• dispatch_queue_create(3)
• dispatch_semaphore_create(3)
• dispatch_time(3)

---

💀 reminder: DISPATCH_TIME_FOREVER means forever. not "a while". not "eventually". FOREVER. don't be out here blocking your main thread unless you truly mean it 🙈

Darwin 🌸 May 1, 2009 🌸 dispatch_group_create(3)

k bye bestie, go group those blocks 💖✨🎀🦋