man/dispatch_time.3

   1 .\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.
   2 .Dd May 1, 2009
   3 .Dt dispatch_time 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_time ,
   7 .Nm dispatch_walltime
   8 .Nd Calculate temporal milestones
   9 .Sh SYNOPSIS
  10 .Fd #include <dispatch/dispatch.h>
  11 .Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ;
  12 .Vt static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull ;
  13 .Ft dispatch_time_t
  14 .Fo dispatch_time
  15 .Fa "dispatch_time_t base" "int64_t offset"
  16 .Fc
  17 .Ft dispatch_time_t
  18 .Fo dispatch_walltime
  19 .Fa "struct timespec *base" "int64_t offset"
  20 .Fc
  21 .Sh DESCRIPTION
  22 The
  23 .Fn dispatch_time
  24 and
  25 .Fn dispatch_walltime
  26 functions provide a simple mechanism for expressing temporal milestones for use
  27 with dispatch functions that need timeouts or operate on a schedule.
  28 .Pp
  29 The
  30 .Fa dispatch_time_t
  31 type is a semi-opaque integer, with only the special values
  32 .Vt DISPATCH_TIME_NOW
  33 and
  34 .Vt DISPATCH_TIME_FOREVER
  35 being externally defined. All other values are represented using an internal
  36 format that is not safe for integer arithmetic or comparison.
  37 The internal format is subject to change.
  38 .Pp
  39 The
  40 .Fn dispatch_time
  41 function returns a milestone relative to an existing milestone after adding
  42 .Fa offset
  43 nanoseconds.
  44 If the
  45 .Fa base
  46 parameter maps internally to a wall clock, then the returned value is
  47 relative to the wall clock.
  48 Otherwise, if
  49 .Fa base
  50 is
  51 .Vt DISPATCH_TIME_NOW ,
  52 then the current time of the default host clock is used.
  53 .Pp
  54 The
  55 .Fn dispatch_walltime
  56 function is useful for creating a milestone relative to a fixed point in time
  57 using the wall clock, as specified by the optional
  58 .Fa base
  59 parameter. If
  60 .Fa base
  61 is NULL, then the current time of the wall clock is used.
  62 .Sh EDGE CONDITIONS
  63 The
  64 .Fn dispatch_time
  65 and
  66 .Fn dispatch_walltime
  67 functions detect overflow and underflow conditions when applying the
  68 .Fa offset
  69 parameter.
  70 .Pp
  71 Overflow causes
  72 .Vt DISPATCH_TIME_FOREVER
  73 to be returned. When
  74 .Fa base
  75 is
  76 .Vt DISPATCH_TIME_FOREVER ,
  77 then the
  78 .Fa offset
  79 parameter is ignored.
  80 .Pp
  81 Underflow causes the smallest representable value to be
  82 returned for a given clock.
  83 .Sh CAVEATS
  84 Under the C language, untyped numbers default to the
  85 .Vt int
  86 type. This can lead to truncation bugs when arithmetic operations with other
  87 numbers are expected to generate a
  88 .Vt int64_t
  89 sized result, such as the
  90 .Fa offset
  91 argument to
  92 .Fn dispatch_time
  93 and
  94 .Fn dispatch_walltime .
  95 When in doubt, use
  96 .Vt ull
  97 as a suffix. For example:
  98 .Bd -literal -offset indent
  99 3ull * NSEC_PER_SEC
 100 .Ed
 101 .Sh EXAMPLES
 102 Create a milestone two seconds in the future:
 103 .Bd -literal -offset indent
 104 milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);
 105 .Ed
 106 .Pp
 107 Create a milestone for use as an infinite timeout:
 108 .Bd -literal -offset indent
 109 milestone = DISPATCH_TIME_FOREVER;
 110 .Ed
 111 .Pp
 112 Create a milestone on Tuesday, January 19, 2038:
 113 .Bd -literal -offset indent
 114 struct timespec ts;
 115 ts.tv_sec = 0x7FFFFFFF;
 116 ts.tv_nsec = 0;
 117 milestone = dispatch_walltime(&ts, 0);
 118 .Ed
 119 .Sh RETURN VALUE
 120 These functions return an abstract value for use with
 121 .Fn dispatch_after ,
 122 .Fn dispatch_group_wait ,
 123 .Fn dispatch_semaphore_wait ,
 124 or
 125 .Fn dispatch_source_set_timer .
 126 .Sh SEE ALSO
 127 .Xr dispatch 3 ,
 128 .Xr dispatch_after 3 ,
 129 .Xr dispatch_group_create 3 ,
 130 .Xr dispatch_semaphore_create 3