dispatch_time(3)

💖 dispatch_time(3) — bestie edition 💖

okay so welcome to the dispatch_time(3) page from the Library Functions Manual, bestie 🫶 we're gonna talk about time (not in the existential way, in the scheduling way, slay).

---

✨ NAME ✨

dispatch_time, dispatch_walltime — calculate temporal milestones 💫

🎀 SYNOPSIS 🎀

#include <dispatch/dispatch.h>

static const dispatch_time_t DISPATCH_TIME_NOW = 0;
static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull;

dispatch_time_t
dispatch_time(dispatch_time_t base, int64_t offset);

dispatch_time_t
dispatch_walltime(struct timespec *base, int64_t offset);

---

🌸 DESCRIPTION 🌸

So dispatch_time() and dispatch_walltime() are literally the easiest way to express temporal milestones — like, the "hey do this thing at this moment" points in time you hand to dispatch functions that need timeouts or run on a schedule. lowkey essential.

The dispatch_time_t type is a semi-opaque integer, and the only values that are externally defined are the special ones: DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER. Every other value gets represented using an internal format that is not safe for integer arithmetic or comparison, bestie. do NOT do math on it, do NOT compare it, just hold it and pass it along 💅 and heads up: the internal format is subject to change. no cap.

Now dispatch_time() returns a milestone relative to an existing milestone, after adding offset nanoseconds. and the way it works is: if the base parameter maps internally to a wall clock, then the value it returns is relative to the wall clock. otherwise, if base is DISPATCH_TIME_NOW, then the current time of the default host clock is used. periodt.

Meanwhile dispatch_walltime() is the one you want for creating a milestone relative to a fixed point in time using the wall clock — that's what the optional base parameter is for. and if base is NULL, then the current time of the wall clock is used. iconic.

---

🔥 EDGE CONDITIONS 🔥

dispatch_time() and dispatch_walltime() are out here detecting overflow and underflow when they apply the offset parameter. they're paying attention, unlike me during lecture 🙈

• Overflow causes DISPATCH_TIME_FOREVER to be returned. and when base is DISPATCH_TIME_FOREVER, then the offset parameter is ignored — like, straight up not read, it said "I'm busy".
• Underflow causes the smallest representable value to be returned for a given clock.

💀 pls note: these are real edge conditions, not vibes. overflow → DISPATCH_TIME_FOREVER. underflow → smallest representable value for that clock. memorize it, it's giving exam question.

---

🦋 EXAMPLES 🦋

Create a milestone two seconds in the future:

milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);

Create a milestone for use as an infinite timeout:

milestone = DISPATCH_TIME_FOREVER;

Create a milestone on Tuesday, January 19, 2038:

struct timespec ts;
ts.tv_sec = 0x7FFFFFFF;
ts.tv_nsec = 0;
milestone = dispatch_walltime(&ts, 0);

---

⭐ RETURN VALUE ⭐

These functions return an abstract value, and you use it with dispatch_after(), dispatch_group_wait(), or dispatch_semaphore_wait(). that's it, that's the whole return value. abstract. mysterious. main character energy 👑

---

💜 SEE ALSO 💜

• dispatch(3)
• dispatch_after(3)
• dispatch_group_create(3)
• dispatch_semaphore_create(3)

---

and that's the whole page, bestie 🌈 this one came straight outta Darwin, dated May 1, 2009 — yeah it's been serving since 2009 and it still ate 💅✨ mwah, go schedule something cute 🎀