dispatch_object(3)

🎀 NAME 🎀

dispatch_object — the whole ~general manipulation of dispatch objects~ situation, bestie 💅

(this is from the Library Functions Manual, and it's serving main character energy in section 3, as it should 🫶)

---

✨ SYNOPSIS ✨

#include <dispatch/dispatch.h>

void
dispatch_retain(dispatch_object_t object);

void
dispatch_release(dispatch_object_t object);

void
dispatch_suspend(dispatch_object_t object);

void
dispatch_resume(dispatch_object_t object);

void *
dispatch_get_context(dispatch_object_t object);

void
dispatch_set_context(dispatch_object_t object, void *context);

void
dispatch_set_finalizer_f(dispatch_object_t object,
    dispatch_function_t finalizer);

like. look at that. seven whole functions. no cap, they're all right there 🦋

---

💜 DESCRIPTION 💜

okay so dispatch objects are these little guys that share a whole set of functions for coordinating memory management, suspension, cancellation and context pointers. it's giving "we all use the same toolbelt" fr fr 🧰

and here's the tea: all dispatch objects are retainable, but not all of them support suspension, context pointers or finalizers. rn it's literally just queues and sources that support these additional interfaces. everyone else is just kinda vibing without them 💀

---

🌸 MEMORY MANGEMENT 🌸

(not me spelling it exactly like the original, we respect the source material in this house 🫡)

so objects that get returned by creation functions in the dispatch framework? you can uniformly retain them and release them with dispatch_retain() and dispatch_release() respectively. cute, consistent, iconic ✨

⚠️ but bestie, listen — the dispatch framework does not guarantee that any given client has the last or only reference to a given object. objects may be retained internally by the system. so don't go acting like you're the only one holding it, because you are not 👑😭

---

🔥 SUSPENSION 🔥

when you wanna pause or un-pause the invocation of blocks on dispatch queues or dispatch sources, you use dispatch_suspend() and dispatch_resume() respectively. easy 💅

the dispatch framework always checks the suspension status before executing a block — but (and this is the important part) such changes never affect a block during execution. that's the non-preemptive part. so basically the suspension of an object is asynchronous, unless it's performed from the context of the target queue for the given object 🦋

💀 and the result of suspending or resuming an object that is not a dispatch queue or a dispatch source is undefined. undefined!! don't do it!! 🙈

Important: suspension applies to all aspects of the dispatch object life cycle, including the finalizer function and the cancellation handler. so it is genuinely important that you balance your calls to dispatch_suspend() and dispatch_resume() such that the dispatch object is fully resumed when the last reference is released. because the result of releasing all references to a dispatch object while it's in a suspended state is undefined. yes, undefined again. we stay dramatic because it stays true 😭💜

---

🎀 CONTEXT POINTERS 🎀

dispatch queues and sources support supplemental context pointers — lil bonus pointers, as a treat 🍓

• you can retrieve the value of the context pointer with dispatch_get_context()
• you can update it with dispatch_set_context()

and dispatch_set_finalizer_f() lets you specify an optional per-object finalizer function. this gets invoked asynchronously if the context pointer is not NULL when the last reference to the object is released. which is literally the framework handing your app an opportunity to free the context data associated with the object. thoughtful king behavior honestly 👑

⚠️ and the result of getting or setting the context of an object that is not a dispatch queue or a dispatch source is undefined. (third time's the charm, we love a consistent warning ⭐)

---

🦋 SEE ALSO 🦋

• dispatch(3)
• dispatch_group_create(3)
• dispatch_queue_create(3)
• dispatch_semaphore_create(3)
• dispatch_source_create(3)

go read those too, they're all part of the friend group fr fr 🌈

---

and that's the whole page, bestie!! this one shipped out of Darwin on May 1, 2009, and it's still out here being useful. slay, honestly. periodt. 💖✨🎀