]> git.saurik.com Git - apple/libdispatch.git/blob - man/dispatch_semaphore_create.3
libdispatch-228.18.tar.gz
[apple/libdispatch.git] / man / dispatch_semaphore_create.3
1 .\" Copyright (c) 2008-2010 Apple Inc. All rights reserved.
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
36 parameter is equal to zero, then the semaphore is useful for synchronizing
37 completion of work.
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
54 parameter is greater than zero, then the semaphore is useful for managing a
55 finite pool of resources.
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
86 function returns zero upon success and non-zero after the timeout expires. If
87 the timeout is DISPATCH_TIME_FOREVER, then
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
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.
104 .Sh SEE ALSO
105 .Xr dispatch 3 ,
106 .Xr dispatch_object 3