[apple/libdispatch.git] / man / dispatch_time.3

.\" 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 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 CAVEATS
Under the C language, untyped numbers default to the
.Vt int
type. This can lead to truncation bugs when arithmetic operations with other
numbers are expected to generate a
.Vt int64_t
sized result, such as the
.Fa offset
argument to
.Fn dispatch_time
and
.Fn dispatch_walltime .
When in doubt, use
.Vt ull
as a suffix. For example:
.Bd -literal -offset indent
3ull * NSEC_PER_SEC
.Ed
.Sh EXAMPLES
Create a milestone two seconds in the future:
.Bd -literal -offset indent
milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * 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
.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
Commit	Line	Data
517da941	1	.\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.
0ab74447 A	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>
c093abd6	11	.Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ;
0ab74447 A	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.
517da941 A	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
0ab74447 A	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 ,
517da941	123	.Fn dispatch_semaphore_wait ,
0ab74447	124	or
517da941	125	.Fn dispatch_source_set_timer .
0ab74447	126	.Sh SEE ALSO
e85f4437	127	.Xr dispatch 3 ,
0ab74447 A	128	.Xr dispatch_after 3 ,
	129	.Xr dispatch_group_create 3 ,
	130	.Xr dispatch_semaphore_create 3