git.saurik.com Git - apple/libdispatch.git/blame_incremental

... / ...

Commit	Line	Data
	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 EXAMPLES
	84	Create a milestone two seconds in the future:
	85	.Bd -literal -offset indent
	86	milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * 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	.Pp
	102	Use a negative delta to create a milestone an hour before the one above:
	103	.Bd -literal -offset indent
	104	milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC);
	105	.Ed
	106	.Sh RETURN VALUE
	107	These functions return an abstract value for use with
	108	.Fn dispatch_after ,
	109	.Fn dispatch_group_wait ,
	110	.Fn dispatch_semaphore_wait ,
	111	or
	112	.Fn dispatch_source_set_timer .
	113	.Sh SEE ALSO
	114	.Xr dispatch 3 ,
	115	.Xr dispatch_after 3 ,
	116	.Xr dispatch_group_create 3 ,
	117	.Xr dispatch_semaphore_create 3