| .\" Copyright (c) 2008-2013 Apple Inc. All rights reserved. |
| .Dd May 1, 2009 |
| .Dt dispatch_time 3 |
| .Os Darwin |
| .Sh NAME |
| .Nm dispatch_time , |
| .Nm dispatch_walltime |
| .Nd Calculate temporal milestones |
| .Sh SYNOPSIS |
| .Fd #include <dispatch/dispatch.h> |
| .Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ; |
| .Vt static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull ; |
| .Ft dispatch_time_t |
| .Fo dispatch_time |
| .Fa "dispatch_time_t base" "int64_t offset" |
| .Fc |
| .Ft dispatch_time_t |
| .Fo dispatch_walltime |
| .Fa "struct timespec *base" "int64_t offset" |
| .Fc |
| .Sh DESCRIPTION |
| The |
| .Fn dispatch_time |
| and |
| .Fn dispatch_walltime |
| functions provide a simple mechanism for expressing temporal milestones for use |
| with dispatch functions that need timeouts or operate on a schedule. |
| .Pp |
| The |
| .Fa dispatch_time_t |
| type is a semi-opaque integer, with only the special values |
| .Vt DISPATCH_TIME_NOW |
| and |
| .Vt 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. |
| .Pp |
| The |
| .Fn dispatch_time |
| function returns a milestone relative to an existing milestone after adding |
| .Fa offset |
| nanoseconds. |
| If the |
| .Fa base |
| parameter maps internally to a wall clock, then the returned value is |
| relative to the wall clock. |
| Otherwise, if |
| .Fa base |
| is |
| .Vt DISPATCH_TIME_NOW , |
| then the current time of the default host clock is used. |
| .Pp |
| The |
| .Fn 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 |
| .Fa base |
| parameter. If |
| .Fa base |
| is NULL, then the current time of the wall clock is used. |
| .Sh EDGE CONDITIONS |
| The |
| .Fn dispatch_time |
| and |
| .Fn dispatch_walltime |
| functions detect overflow and underflow conditions when applying the |
| .Fa offset |
| parameter. |
| .Pp |
| Overflow causes |
| .Vt DISPATCH_TIME_FOREVER |
| to be returned. When |
| .Fa base |
| is |
| .Vt DISPATCH_TIME_FOREVER , |
| then the |
| .Fa offset |
| parameter is ignored. |
| .Pp |
| Underflow causes the smallest representable value to be |
| returned for a given clock. |
| .Sh EXAMPLES |
| Create a milestone two seconds in the future: |
| .Bd -literal -offset indent |
| milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC); |
| .Ed |
| .Pp |
| Create a milestone for use as an infinite timeout: |
| .Bd -literal -offset indent |
| milestone = DISPATCH_TIME_FOREVER; |
| .Ed |
| .Pp |
| Create a milestone on Tuesday, January 19, 2038: |
| .Bd -literal -offset indent |
| struct timespec ts; |
| ts.tv_sec = 0x7FFFFFFF; |
| ts.tv_nsec = 0; |
| milestone = dispatch_walltime(&ts, 0); |
| .Ed |
| .Pp |
| Use a negative delta to create a milestone an hour before the one above: |
| .Bd -literal -offset indent |
| milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC); |
| .Ed |
| .Sh RETURN VALUE |
| These functions return an abstract value for use with |
| .Fn dispatch_after , |
| .Fn dispatch_group_wait , |
| .Fn dispatch_semaphore_wait , |
| or |
| .Fn dispatch_source_set_timer . |
| .Sh SEE ALSO |
| .Xr dispatch 3 , |
| .Xr dispatch_after 3 , |
| .Xr dispatch_group_create 3 , |
| .Xr dispatch_semaphore_create 3 |