man/dispatch_time.3

   1 .\" Copyright (c) 2008-2009 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 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 EXAMPLES
  84 Create a milestone two seconds in the future:
  85 .Bd -literal -offset indent
  86 milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);
  87 .Ed
  88 .Pp
  89 Create a milestone for use as an infinite timeout:
  90 .Bd -literal -offset indent
  91 milestone = DISPATCH_TIME_FOREVER;
  92 .Ed
  93 .Pp
  94 Create a milestone on Tuesday, January 19, 2038:
  95 .Bd -literal -offset indent
  96 struct timespec ts;
  97 ts.tv_sec = 0x7FFFFFFF;
  98 ts.tv_nsec = 0;
  99 milestone = dispatch_walltime(&ts, 0);
 100 .Ed
 101 .Sh RETURN VALUE
 102 These functions return an abstract value for use with
 103 .Fn dispatch_after ,
 104 .Fn dispatch_group_wait ,
 105 or
 106 .Fn dispatch_semaphore_wait .
 107 .Sh SEE ALSO
 108 .Xr dispatch 3 ,
 109 .Xr dispatch_after 3 ,
 110 .Xr dispatch_group_create 3 ,
 111 .Xr dispatch_semaphore_create 3