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

.\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
.Dd May 1, 2009
.Dt dispatch_semaphore_create 3
.Os Darwin
.Sh NAME
.Nm dispatch_semaphore_create ,
.Nm dispatch_semaphore_signal ,
.Nm dispatch_semaphore_wait
.Nd synchronized counting semaphore
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Ft dispatch_semaphore_t
.Fo dispatch_semaphore_create
.Fa "long count"
.Fc
.Ft long
.Fo dispatch_semaphore_signal
.Fa "dispatch_semaphore_t semaphore"
.Fc
.Ft long
.Fo dispatch_semaphore_wait
.Fa "dispatch_semaphore_t semaphore" "dispatch_time_t timeout"
.Fc
.Sh DESCRIPTION
Dispatch semaphores are used to synchronize threads.
The
.Fa timeout
parameter is creatable with the
.Xr dispatch_time 3
or
.Xr dispatch_walltime 3
functions.
.Sh COMPLETION SYNCHRONIZATION
If the
.Fa count
parameter is equal to zero, then the semaphore is useful for synchronizing
completion of work.
For example:
.Bd -literal -offset indent
sema = dispatch_semaphore_create(0);

dispatch_async(queue, ^{
	foo();
	dispatch_semaphore_signal(sema);
});

bar();

dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
.Ed
.Sh FINITE RESOURCE POOL
If the
.Fa count
parameter is greater than zero, then the semaphore is useful for managing a
finite pool of resources.
For example, a library that wants to limit Unix descriptor usage:
.Bd -literal -offset indent
sema = dispatch_semaphore_create(getdtablesize() / 4);
.Ed
.Pp
At each Unix FD allocation:
.Bd -literal -offset indent
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
fd = open("/etc/services", O_RDONLY);
.Ed
.Pp
When each FD is closed:
.Bd -literal -offset indent
close(fd);
dispatch_semaphore_signal(sema);
.Ed
.Sh RETURN VALUES
The
.Fn dispatch_semaphore_create
function returns NULL if no memory is available or if the
.Fa count
parameter is less than zero.
.Pp
The
.Fn dispatch_semaphore_signal
function returns non-zero when a thread is woken.
Otherwise, zero is returned.
.Pp
The
.Fn dispatch_semaphore_wait
function returns zero upon success and non-zero after the timeout expires. If
the timeout is DISPATCH_TIME_FOREVER, then
.Fn dispatch_semaphore_wait
waits forever and always returns zero.
.Sh MEMORY MODEL
Dispatch semaphores are retained and released via calls to
.Fn dispatch_retain
and
.Fn dispatch_release .
.Sh CAVEATS
Unbalanced dispatch semaphores cannot be released.
For a given semaphore, calls to
.Fn dispatch_semaphore_signal
and
.Fn dispatch_semaphore_wait
must be balanced before
.Fn dispatch_release
is called on it.
.Sh SEE ALSO
.Xr dispatch 3 ,
.Xr dispatch_object 3
Commit	Line	Data
517da941	1	.\" Copyright (c) 2008-2012 Apple Inc. All rights reserved.
0ab74447 A	2	.Dd May 1, 2009
	3	.Dt dispatch_semaphore_create 3
	4	.Os Darwin
	5	.Sh NAME
	6	.Nm dispatch_semaphore_create ,
	7	.Nm dispatch_semaphore_signal ,
	8	.Nm dispatch_semaphore_wait
	9	.Nd synchronized counting semaphore
	10	.Sh SYNOPSIS
	11	.Fd #include <dispatch/dispatch.h>
	12	.Ft dispatch_semaphore_t
	13	.Fo dispatch_semaphore_create
	14	.Fa "long count"
	15	.Fc
	16	.Ft long
	17	.Fo dispatch_semaphore_signal
	18	.Fa "dispatch_semaphore_t semaphore"
	19	.Fc
	20	.Ft long
	21	.Fo dispatch_semaphore_wait
	22	.Fa "dispatch_semaphore_t semaphore" "dispatch_time_t timeout"
	23	.Fc
	24	.Sh DESCRIPTION
	25	Dispatch semaphores are used to synchronize threads.
	26	The
	27	.Fa timeout
	28	parameter is creatable with the
	29	.Xr dispatch_time 3
	30	or
	31	.Xr dispatch_walltime 3
	32	functions.
	33	.Sh COMPLETION SYNCHRONIZATION
	34	If the
	35	.Fa count
e85f4437 A	36	parameter is equal to zero, then the semaphore is useful for synchronizing
e85f4437 A	37	completion of work.
0ab74447 A	38	For example:
	39	.Bd -literal -offset indent
	40	sema = dispatch_semaphore_create(0);
	41
	42	dispatch_async(queue, ^{
	43	foo();
	44	dispatch_semaphore_signal(sema);
	45	});
	46
	47	bar();
	48
	49	dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
	50	.Ed
	51	.Sh FINITE RESOURCE POOL
	52	If the
	53	.Fa count
e85f4437 A	54	parameter is greater than zero, then the semaphore is useful for managing a
e85f4437 A	55	finite pool of resources.
0ab74447 A	56	For example, a library that wants to limit Unix descriptor usage:
	57	.Bd -literal -offset indent
	58	sema = dispatch_semaphore_create(getdtablesize() / 4);
	59	.Ed
	60	.Pp
	61	At each Unix FD allocation:
	62	.Bd -literal -offset indent
	63	dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
	64	fd = open("/etc/services", O_RDONLY);
	65	.Ed
	66	.Pp
	67	When each FD is closed:
	68	.Bd -literal -offset indent
	69	close(fd);
	70	dispatch_semaphore_signal(sema);
	71	.Ed
	72	.Sh RETURN VALUES
	73	The
	74	.Fn dispatch_semaphore_create
	75	function returns NULL if no memory is available or if the
	76	.Fa count
	77	parameter is less than zero.
	78	.Pp
	79	The
	80	.Fn dispatch_semaphore_signal
	81	function returns non-zero when a thread is woken.
	82	Otherwise, zero is returned.
	83	.Pp
	84	The
	85	.Fn dispatch_semaphore_wait
e85f4437 A	86	function returns zero upon success and non-zero after the timeout expires. If
e85f4437 A	87	the timeout is DISPATCH_TIME_FOREVER, then
0ab74447 A	88	.Fn dispatch_semaphore_wait
	89	waits forever and always returns zero.
	90	.Sh MEMORY MODEL
	91	Dispatch semaphores are retained and released via calls to
	92	.Fn dispatch_retain
	93	and
	94	.Fn dispatch_release .
	95	.Sh CAVEATS
e85f4437 A	96	Unbalanced dispatch semaphores cannot be released.
	97	For a given semaphore, calls to
	98	.Fn dispatch_semaphore_signal
	99	and
	100	.Fn dispatch_semaphore_wait
	101	must be balanced before
	102	.Fn dispatch_release
	103	is called on it.
0ab74447	104	.Sh SEE ALSO
e85f4437	105	.Xr dispatch 3 ,
0ab74447	106	.Xr dispatch_object 3