1PTHREAD_MUTEXATTR_DESTROY(3PP)OSIX Programmer's ManuPaTlHREAD_MUTEXATTR_DESTROY(3P)
2
3
4

PROLOG

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
11

NAME

13       pthread_mutexattr_destroy, pthread_mutexattr_init —  destroy  and  ini‐
14       tialize the mutex attributes object
15

SYNOPSIS

17       #include <pthread.h>
18
19       int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
20       int pthread_mutexattr_init(pthread_mutexattr_t *attr);
21

DESCRIPTION

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
28       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
32       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
36       Results are undefined if pthread_mutexattr_init() is called  specifying
37       an already initialized attr attributes object.
38
39       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
43       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

RETURN VALUE

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

ERRORS

53       The pthread_mutexattr_init() function shall fail if:
54
55       ENOMEM Insufficient  memory  exists  to initialize the mutex attributes
56              object.
57
58       These functions shall not return an error code of [EINTR].
59
60       The following sections are informative.
61

EXAMPLES

63       None.
64

APPLICATION USAGE

66       None.
67

RATIONALE

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
74       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
82       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
93   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
100       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
115   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
122       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
126       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
131       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
135       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
145           /* 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
153           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
159           /* 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
167           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
175               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
195           semaphore_t *
196           semaphore_open(char *semaphore_name)
197           {
198               int fd;
199               semaphore_t *semap;
200
201               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
211           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
221           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
231           void
232           semaphore_close(semaphore_t *semap)
233           {
234               munmap((void *) semap, sizeof(semaphore_t));
235           }
236
237       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
243           /* create.c */
244           #include "pthread.h"
245           #include "sem.h"
246
247           int
248           main()
249           {
250               semaphore_t *semap;
251
252               semap = semaphore_create("/tmp/semaphore");
253               if (semap == NULL)
254                   exit(1);
255               semaphore_close(semap);
256               return (0);
257           }
258
259           /* post */
260           #include "pthread.h"
261           #include "sem.h"
262
263           int
264           main()
265           {
266               semaphore_t *semap;
267
268               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
276           /* wait */
277           #include "pthread.h"
278           #include "sem.h"
279
280           int
281           main()
282           {
283               semaphore_t *semap;
284
285               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

FUTURE DIRECTIONS

294       None.
295

SEE ALSO

297       pthread_cond_destroy(), pthread_create(), pthread_mutex_destroy()
298
299       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
313       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 .
317
318
319
320IEEE/The Open Group                  2013        PTHREAD_MUTEXATTR_DESTROY(3P)
Impressum