---
name: "dispatch_time"
section: "3"
platform: "linux"
package: "libdispatch"
version: "6.2.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/dispatch_time"
---

# dispatch\_time(3)

Calculate temporal milestones

## NAME

**dispatch\_time**, **dispatch\_walltime** – Calculate temporal milestones

## SYNOPSIS

**#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

The **dispatch\_time**() and **dispatch\_walltime**() functions provide a simple mechanism for expressing temporal milestones for use with dispatch functions that need timeouts or operate on a schedule.

The *dispatch\_time\_t* type is a semi-opaque integer, with only the special values *DISPATCH\_TIME\_NOW*, *DISPATCH\_WALLTIME\_NOW* and *DISPATCH\_TIME\_FOREVER* being externally defined. All other values are represented using an internal format that is not safe for integer arithmetic or comparison. The internal format is subject to change.

The **dispatch\_time**() function returns a milestone relative to an existing milestone after adding *offset* nanoseconds. If the *base* parameter maps internally to a wall clock or 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. On Apple platforms, the value of the default host clock is obtained from *mach\_absolute\_time()*.

The **dispatch\_walltime**() function is useful for creating a milestone relative to a fixed point in time using the wall clock, as specified by the optional *base* parameter. If *base* is NULL, then the current time of the wall clock is used. *dispatch\_walltime(NULL,* *offset)* is equivalent to *dispatch\_time(DISPATCH\_WALLTIME\_NOW,* *offset)*.

## EDGE CONDITIONS

The **dispatch\_time**() and **dispatch\_walltime**() functions detect overflow and underflow conditions when applying the *offset* parameter.

Overflow causes *DISPATCH\_TIME\_FOREVER* to be returned. When *base* is *DISPATCH\_TIME\_FOREVER*, then the *offset* parameter is ignored.

Underflow causes the smallest representable value to be returned for a given clock.

## 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);
```

## RETURN VALUE

These functions return an abstract value for use with **dispatch\_after**(), **dispatch\_group\_wait**(), **dispatch\_semaphore\_wait**(), or **dispatch\_source\_set\_timer**().

## SEE ALSO

[dispatch(3)](/dispatch/3.md), [dispatch\_after(3)](/dispatch_after/3.md), [dispatch\_group\_create(3)](/dispatch_group_create/3.md), [dispatch\_semaphore\_create(3)](/dispatch_semaphore_create/3.md)