dispatch_time(3)

💖 dispatch_time — bestie we're calculating temporal milestones ✨

okay so this is dispatch_time(3) from the Library Functions Manual, and honestly? it's giving time-travel-adjacent. it's giving "when should this thing fire." you're gonna love it, no cap. 🕰️🦋

---

🌸 NAME 🌸

dispatch_time, dispatch_walltime — Calculate temporal milestones

---

✨ SYNOPSIS ✨

like, here's the whole vibe upfront, bestie:

#include <dispatch/dispatch.h>

static const dispatch_time_t DISPATCH_TIME_NOW = 0ull;
static const dispatch_time_t DISPATCH_WALLTIME_NOW = ~1ull;
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 the two functions that give you a simple mechanism for expressing temporal milestones for use with dispatch functions that need timeouts or operate on a schedule. that's the whole job. expressing milestones. slay.

okay so the dispatch_time_t type? it's a semi-opaque integer. and here's the tea, the only values that are externally defined are the special ones:

• DISPATCH_TIME_NOW
• DISPATCH_WALLTIME_NOW
• DISPATCH_TIME_FOREVER

every single other value is represented using an internal format that is not safe for integer arithmetic or comparison. 😭 not safe!! do not do math on it, do not compare it, do not look at it funny. and the internal format is subject to change, so literally don't get attached. periodt.

now, dispatch_time() returns a milestone relative to an existing milestone after adding offset nanoseconds. so like, take a base, add some nanos, boom — new milestone. and the clock situation:

• if the base parameter maps internally to a wall clock, or if it is DISPATCH_WALLTIME_NOW, then the returned value is relative to the wall clock.
• otherwise, if base is DISPATCH_TIME_NOW, then the current time of the default host clock is used.
• and on Apple platforms, the value of the default host clock is obtained from mach_absolute_time(). cute detail, love that for us. 🍓

then there's dispatch_walltime(), which is the one you want when you're creating a milestone relative to a fixed point in time using the wall clock, as specified by the optional base parameter. it's giving "anchor me to an actual moment."

• if base is NULL, then the current time of the wall clock is used.
• and dispatch_walltime(NULL, offset) is equivalent to dispatch_time(DISPATCH_WALLTIME_NOW, offset). 🫶

---

🔥 EDGE CONDITIONS 🔥

not me having to tell you about the edge conditions, but we must. dispatch_time() and dispatch_walltime() detect overflow and underflow conditions when applying the offset parameter.

• Overflow causes DISPATCH_TIME_FOREVER to be returned. and when base is DISPATCH_TIME_FOREVER, then the offset parameter is ignored. like it's just not invited to the party. 💀
• Underflow causes the smallest representable value to be returned for a given clock.

bestie these are real edge conditions, not a drill — overflow and underflow are handled for you, but the results are the results. 🌈

---

🎀 EXAMPLES 🎀

Create a milestone two seconds in the future, relative to the default clock:

milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC);

Create a milestone two seconds in the future, in wall clock time:

milestone = dispatch_time(DISPATCH_WALLTIME_NOW, 2 * 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);

Use a negative delta to create a milestone an hour before the one above:

milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC);

okay the 2038 one is iconic and slightly ominous but we move. 👑

---

⭐ RETURN VALUE ⭐

these functions return an abstract value for use with dispatch_after(), dispatch_group_wait(), dispatch_semaphore_wait(), or dispatch_source_set_timer().

so like, don't try to read it, don't try to do arithmetic on it — just hand it to one of those and let them cook. 💜

---

🌈 SEE ALSO 🌈

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

---

and that's the whole page, bestie!! this one's from Darwin, dated May 1, 2009, and it's dispatch_time(3) forever and ever — DISPATCH_TIME_FOREVER, even. 💖✨🦋 go forth and schedule things responsibly. mwah. 🎀