---
name: "dispatch_walltime"
section: "3"
platform: "linux"
package: "libdispatch-dev"
version: "0~svn197-3.2"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/dispatch_time"
---

# dispatch\_walltime(3)

Calculate temporal milestones

Part of [dispatch\_time(3)](/dispatch_time/3.md).

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

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* 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, then the returned value is relative to the wall clock. Otherwise, if *base* is *DISPATCH\_TIME\_NOW*, then the the current time of the default host clock is used.

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.

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

```
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 for use with **dispatch\_after**(), **dispatch\_group\_wait**(), or **dispatch\_semaphore\_wait**().

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