1PTHREAD_MUTEXATTR_DESTROY(3PP)OSIX Programmer's ManuPaTlHREAD_MUTEXATTR_DESTROY(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 pthread_mutexattr_destroy, pthread_mutexattr_init — destroy and ini‐
14 tialize the mutex attributes object
15
17 #include <pthread.h>
18 int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
20 int pthread_mutexattr_init(pthread_mutexattr_t *attr);
21
23 The pthread_mutexattr_destroy() function shall destroy a mutex
24 attributes object; the object becomes, in effect, uninitialized. An
25 implementation may cause pthread_mutexattr_destroy() to set the object
26 referenced by attr to an invalid value.
27 A destroyed attr attributes object can be reinitialized using
29 pthread_mutexattr_init(); the results of otherwise referencing the
30 object after it has been destroyed are undefined.
31 The pthread_mutexattr_init() function shall initialize a mutex
33 attributes object attr with the default value for all of the attributes
34 defined by the implementation.
35 Results are undefined if pthread_mutexattr_init() is called specifying
37 an already initialized attr attributes object.
38 After a mutex attributes object has been used to initialize one or more
40 mutexes, any function affecting the attributes object (including
41 destruction) shall not affect any previously initialized mutexes.
42 The behavior is undefined if the value specified by the attr argument
44 to pthread_mutexattr_destroy() does not refer to an initialized mutex
45 attributes object.
46
48 Upon successful completion, pthread_mutexattr_destroy() and
49 pthread_mutexattr_init() shall return zero; otherwise, an error number
50 shall be returned to indicate the error.
51
53 The pthread_mutexattr_init() function shall fail if:
54 ENOMEM Insufficient memory exists to initialize the mutex attributes
56 object.
57 These functions shall not return an error code of [EINTR].
59 The following sections are informative.
61
63 None.
64
66 None.
67
69 If an implementation detects that the value specified by the attr argu‐
70 ment to pthread_mutexattr_destroy() does not refer to an initialized
71 mutex attributes object, it is recommended that the function should
72 fail and report an [EINVAL] error.
73 See pthread_attr_destroy() for a general explanation of attributes.
75 Attributes objects allow implementations to experiment with useful
76 extensions and permit extension of this volume of POSIX.1‐2008 without
77 changing the existing functions. Thus, they provide for future extensi‐
78 bility of this volume of POSIX.1‐2008 and reduce the temptation to
79 standardize prematurely on semantics that are not yet widely imple‐
80 mented or understood.
81 Examples of possible additional mutex attributes that have been dis‐
83 cussed are spin_only, limited_spin, no_spin, recursive, and metered.
84 (To explain what the latter attributes might mean: recursive mutexes
85 would allow for multiple re-locking by the current owner; metered
86 mutexes would transparently keep records of queue length, wait time,
87 and so on.) Since there is not yet wide agreement on the usefulness of
88 these resulting from shared implementation and usage experience, they
89 are not yet specified in this volume of POSIX.1‐2008. Mutex attributes
90 objects, however, make it possible to test out these concepts for pos‐
91 sible standardization at a later time.
92 Mutex Attributes and Performance
94 Care has been taken to ensure that the default values of the mutex
95 attributes have been defined such that mutexes initialized with the
96 defaults have simple enough semantics so that the locking and unlocking
97 can be done with the equivalent of a test-and-set instruction (plus
98 possibly a few other basic instructions).
99 There is at least one implementation method that can be used to reduce
101 the cost of testing at lock-time if a mutex has non-default attributes.
102 One such method that an implementation can employ (and this can be made
103 fully transparent to fully conforming POSIX applications) is to
104 secretly pre-lock any mutexes that are initialized to non-default
105 attributes. Any later attempt to lock such a mutex causes the implemen‐
106 tation to branch to the ``slow path'' as if the mutex were unavailable;
107 then, on the slow path, the implementation can do the ``real work'' to
108 lock a non-default mutex. The underlying unlock operation is more com‐
109 plicated since the implementation never really wants to release the
110 pre-lock on this kind of mutex. This illustrates that, depending on the
111 hardware, there may be certain optimizations that can be used so that
112 whatever mutex attributes are considered ``most frequently used'' can
113 be processed most efficiently.
114 Process Shared Memory and Synchronization
116 The existence of memory mapping functions in this volume of
117 POSIX.1‐2008 leads to the possibility that an application may allocate
118 the synchronization objects from this section in memory that is
119 accessed by multiple processes (and therefore, by threads of multiple
120 processes).
121 In order to permit such usage, while at the same time keeping the usual
123 case (that is, usage within a single process) efficient, a process-
124 shared option has been defined.
125 If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option,
127 then the process-shared attribute can be used to indicate that mutexes
128 or condition variables may be accessed by threads of multiple pro‐
129 cesses.
130 The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the
132 process-shared attribute so that the most efficient forms of these syn‐
133 chronization objects are created by default.
134 Synchronization variables that are initialized with the
136 PTHREAD_PROCESS_PRIVATE process-shared attribute may only be operated
137 on by threads in the process that initialized them. Synchronization
138 variables that are initialized with the PTHREAD_PROCESS_SHARED process-
139 shared attribute may be operated on by any thread in any process that
140 has access to it. In particular, these processes may exist beyond the
141 lifetime of the initializing process. For example, the following code
142 implements a simple counting semaphore in a mapped file that may be
143 used by many processes.
144 /* sem.h */
146 struct semaphore {
147 pthread_mutex_t lock;
148 pthread_cond_t nonzero;
149 unsigned count;
150 };
151 typedef struct semaphore semaphore_t;
152 semaphore_t *semaphore_create(char *semaphore_name);
154 semaphore_t *semaphore_open(char *semaphore_name);
155 void semaphore_post(semaphore_t *semap);
156 void semaphore_wait(semaphore_t *semap);
157 void semaphore_close(semaphore_t *semap);
158 /* sem.c */
160 #include <sys/types.h>
161 #include <sys/stat.h>
162 #include <sys/mman.h>
163 #include <fcntl.h>
164 #include <pthread.h>
165 #include "sem.h"
166 semaphore_t *
168 semaphore_create(char *semaphore_name)
169 {
170 int fd;
171 semaphore_t *semap;
172 pthread_mutexattr_t psharedm;
173 pthread_condattr_t psharedc;
174 fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666);
176 if (fd < 0)
177 return (NULL);
178 (void) ftruncate(fd, sizeof(semaphore_t));
179 (void) pthread_mutexattr_init(&psharedm);
180 (void) pthread_mutexattr_setpshared(&psharedm,
181 PTHREAD_PROCESS_SHARED);
182 (void) pthread_condattr_init(&psharedc);
183 (void) pthread_condattr_setpshared(&psharedc,
184 PTHREAD_PROCESS_SHARED);
185 semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
186 PROT_READ | PROT_WRITE, MAP_SHARED,
187 fd, 0);
188 close (fd);
189 (void) pthread_mutex_init(&semap->lock, &psharedm);
190 (void) pthread_cond_init(&semap->nonzero, &psharedc);
191 semap->count = 0;
192 return (semap);
193 }
194 semaphore_t *
196 semaphore_open(char *semaphore_name)
197 {
198 int fd;
199 semaphore_t *semap;
200 fd = open(semaphore_name, O_RDWR, 0666);
202 if (fd < 0)
203 return (NULL);
204 semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
205 PROT_READ | PROT_WRITE, MAP_SHARED,
206 fd, 0);
207 close (fd);
208 return (semap);
209 }
210 void
212 semaphore_post(semaphore_t *semap)
213 {
214 pthread_mutex_lock(&semap->lock);
215 if (semap->count == 0)
216 pthread_cond_signal(&semapx->nonzero);
217 semap->count++;
218 pthread_mutex_unlock(&semap->lock);
219 }
220 void
222 semaphore_wait(semaphore_t *semap)
223 {
224 pthread_mutex_lock(&semap->lock);
225 while (semap->count == 0)
226 pthread_cond_wait(&semap->nonzero, &semap->lock);
227 semap->count--;
228 pthread_mutex_unlock(&semap->lock);
229 }
230 void
232 semaphore_close(semaphore_t *semap)
233 {
234 munmap((void *) semap, sizeof(semaphore_t));
235 }
236 The following code is for three separate processes that create, post,
238 and wait on a semaphore in the file /tmp/semaphore. Once the file is
239 created, the post and wait programs increment and decrement the count‐
240 ing semaphore (waiting and waking as required) even though they did not
241 initialize the semaphore.
242 /* create.c */
244 #include "pthread.h"
245 #include "sem.h"
246 int
248 main()
249 {
250 semaphore_t *semap;
251 semap = semaphore_create("/tmp/semaphore");
253 if (semap == NULL)
254 exit(1);
255 semaphore_close(semap);
256 return (0);
257 }
258 /* post */
260 #include "pthread.h"
261 #include "sem.h"
262 int
264 main()
265 {
266 semaphore_t *semap;
267 semap = semaphore_open("/tmp/semaphore");
269 if (semap == NULL)
270 exit(1);
271 semaphore_post(semap);
272 semaphore_close(semap);
273 return (0);
274 }
275 /* wait */
277 #include "pthread.h"
278 #include "sem.h"
279 int
281 main()
282 {
283 semaphore_t *semap;
284 semap = semaphore_open("/tmp/semaphore");
286 if (semap == NULL)
287 exit(1);
288 semaphore_wait(semap);
289 semaphore_close(semap);
290 return (0);
291 }
292
294 None.
295
297 pthread_cond_destroy(), pthread_create(), pthread_mutex_destroy()
298 The Base Definitions volume of POSIX.1‐2008, <pthread.h>
300
302 Portions of this text are reprinted and reproduced in electronic form
303 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
304 -- Portable Operating System Interface (POSIX), The Open Group Base
305 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
306 cal and Electronics Engineers, Inc and The Open Group. (This is
307 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
308 event of any discrepancy between this version and the original IEEE and
309 The Open Group Standard, the original IEEE and The Open Group Standard
310 is the referee document. The original Standard can be obtained online
311 at http://www.unix.org/online.html .
312 Any typographical or formatting errors that appear in this page are
314 most likely to have been introduced during the conversion of the source
315 files to man page format. To report such errors, see https://www.ker‐
316 nel.org/doc/man-pages/reporting_bugs.html .
317IEEE/The Open Group 2013 PTHREAD_MUTEXATTR_DESTROY(3P)