Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dispatch_time(3)	 BSD Library Functions Manual	      dispatch_time(3)

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	func-
     tions 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 de-
     fined. 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	cur-
     rent time of the default host clock is used.

     The dispatch_walltime() function is useful	for creating a milestone rela-
     tive 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_after(3), dispatch_group_create(3),
     dispatch_semaphore_create(3)

Darwin				  May 1, 2009				Darwin

NAME | SYNOPSIS | DESCRIPTION | EDGE CONDITIONS | EXAMPLES | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dispatch_time&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help