dispatch_group_create(3)

✨ dispatch_group_create(3) ✨

okay bestie, listen up 💖 this one's from the Library Functions Manual, and it's all about dispatch_group_create and its whole little squad: dispatch_group_async, dispatch_group_wait, dispatch_group_notify — group blocks submitted to queues. no cap, this is the good stuff 🎀

---

🌸 NAME 🌸

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

---

🦋 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. Applications may use dispatch groups to wait for the completion of blocks associated with the group. it's giving "group chat for blocks" and honestly? iconic 🫶

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

The dispatch_group_enter() and dispatch_group_leave() functions update the number of blocks running within a group. think of it like a little counter you bump up and down — enter goes up, leave goes down, balance is the whole point ⚖️

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. literally waiting forever bestie, it said what it said 💀

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 the group and it still shows up for you, that's loyalty fr fr 🥹

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);
        });
}

like it's just doing the retain + enter + async + leave + release dance for you so you don't have to 🧚

---

🌈 RETURN VALUE 🌈

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

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. zero = slay, non-zero = the clock ran out ⏰

---

💜 MEMORY MODEL 💜

Dispatch groups are retained and released via calls to dispatch_retain() and dispatch_release(). that's the whole deal, keep the count right and you're golden 👑

---

🍓 FUNDAMENTALS 🍓

The dispatch_group_async() and dispatch_group_notify() functions are wrappers around dispatch_group_async_f() and dispatch_group_notify_f() respectively. yeah, the block versions are just the cute little front-ends for the _f function-pointer versions 🙈

---

🔥 CAVEATS 🔥

bestie this is the part where you actually pay attention, no scrolling past 👀

In order to ensure deterministic behavior, it is recommended to call dispatch_group_wait() only once all blocks have been submitted to the group. If it is later determined that new blocks should be run, it is recommended not to reuse an already-running group, but to create a new group. do NOT recycle a group mid-flight, just make a fresh one, periodt 💅

dispatch_group_wait() returns as soon as there are exactly zero enqueued or running blocks associated with a group (more precisely, as soon as every dispatch_group_enter() call has been balanced by a dispatch_group_leave() call). If one thread waits for a group while another thread submits new blocks to the group, then the count of associated blocks might momentarily reach zero before all blocks have been submitted. If this happens, dispatch_group_wait() will return too early: some blocks associated with the group have finished, but some have not yet been submitted or run. it's giving "count hit zero for a sec and the waiter woke up way too soon" 😭

However, as a special case, a block associated with a group may submit new blocks associated with its own group. In this case, the behavior is deterministic: a waiting thread will not wake up until the newly submitted blocks have also finished. oh so that's the exception, iconic exception behavior honestly ✨

All of the foregoing also applies to dispath_group_notify() as well, with "block to be submitted" substituted for "waiting thread". (yes, that spelling is exactly what's in the manual, i'm not touching it, i'm just the messenger 🫶)

---

🌟 SEE ALSO 🌟

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

---

and that's the whole page bestie 💖 this one's from Darwin, dated May 1, 2009 — yeah it's an oldie but it still eats, the whole dispatch_group_create(3) saga is timeless 🎀 bye love u, go balance your enters and leaves 🌸