logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_mutexattr_destroy.3p (11054B)


  1. '\" et
  2. .TH PTHREAD_MUTEXATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_mutexattr_destroy,
  12. pthread_mutexattr_init
  13. \(em destroy and initialize the mutex attributes object
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP);
  20. int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIpthread_mutexattr_destroy\fR()
  25. function shall destroy a mutex attributes object; the object becomes,
  26. in effect, uninitialized. An implementation may cause
  27. \fIpthread_mutexattr_destroy\fR()
  28. to set the object referenced by
  29. .IR attr
  30. to an invalid value.
  31. .P
  32. A destroyed
  33. .IR attr
  34. attributes object can be reinitialized using
  35. \fIpthread_mutexattr_init\fR();
  36. the results of otherwise referencing the object after it
  37. has been destroyed are undefined.
  38. .P
  39. The
  40. \fIpthread_mutexattr_init\fR()
  41. function shall initialize a mutex attributes object
  42. .IR attr
  43. with the default value for all of the attributes defined by the
  44. implementation.
  45. .P
  46. Results are undefined if
  47. \fIpthread_mutexattr_init\fR()
  48. is called specifying an already initialized
  49. .IR attr
  50. attributes object.
  51. .P
  52. After a mutex attributes object has been used to initialize one or more
  53. mutexes, any function affecting the attributes object (including
  54. destruction) shall not affect any previously initialized mutexes.
  55. .P
  56. The behavior is undefined if the value specified by the
  57. .IR attr
  58. argument to
  59. \fIpthread_mutexattr_destroy\fR()
  60. does not refer to an initialized mutex attributes object.
  61. .SH "RETURN VALUE"
  62. Upon successful completion,
  63. \fIpthread_mutexattr_destroy\fR()
  64. and
  65. \fIpthread_mutexattr_init\fR()
  66. shall return zero; otherwise, an error number shall be returned to
  67. indicate the error.
  68. .SH ERRORS
  69. The
  70. \fIpthread_mutexattr_init\fR()
  71. function shall fail if:
  72. .TP
  73. .BR ENOMEM
  74. Insufficient memory exists to initialize the mutex attributes object.
  75. .P
  76. These functions shall not return an error code of
  77. .BR [EINTR] .
  78. .LP
  79. .IR "The following sections are informative."
  80. .SH EXAMPLES
  81. None.
  82. .SH "APPLICATION USAGE"
  83. None.
  84. .SH RATIONALE
  85. If an implementation detects that the value specified by the
  86. .IR attr
  87. argument to
  88. \fIpthread_mutexattr_destroy\fR()
  89. does not refer to an initialized mutex attributes object, it is
  90. recommended that the function should fail and report an
  91. .BR [EINVAL]
  92. error.
  93. .P
  94. See
  95. .IR "\fIpthread_attr_destroy\fR\^(\|)"
  96. for a general explanation of attributes. Attributes objects allow
  97. implementations to experiment with useful extensions and permit
  98. extension of this volume of POSIX.1\(hy2017 without changing the existing functions. Thus, they
  99. provide for future extensibility of this volume of POSIX.1\(hy2017 and reduce the temptation to
  100. standardize prematurely on semantics that are not yet widely
  101. implemented or understood.
  102. .P
  103. Examples of possible additional mutex attributes that have been
  104. discussed are
  105. .IR spin_only ,
  106. .IR limited_spin ,
  107. .IR no_spin ,
  108. .IR recursive ,
  109. and
  110. .IR metered .
  111. (To explain what the latter attributes might mean: recursive mutexes
  112. would allow for multiple re-locking by the current owner; metered
  113. mutexes would transparently keep records of queue length, wait time,
  114. and so on.) Since there is not yet wide agreement on the usefulness of
  115. these resulting from shared implementation and usage experience, they
  116. are not yet specified in this volume of POSIX.1\(hy2017. Mutex attributes objects,
  117. however, make it possible to test out these concepts for possible
  118. standardization at a later time.
  119. .SS "Mutex Attributes and Performance"
  120. .P
  121. Care has been taken to ensure that the default values of the mutex
  122. attributes have been defined such that mutexes initialized with the
  123. defaults have simple enough semantics so that the locking and unlocking
  124. can be done with the equivalent of a test-and-set instruction (plus
  125. possibly a few other basic instructions).
  126. .P
  127. There is at least one implementation method that can be used to reduce
  128. the cost of testing at lock-time if a mutex has non-default
  129. attributes. One such method that an implementation can employ (and
  130. this can be made fully transparent to fully conforming POSIX
  131. applications) is to secretly pre-lock any mutexes that are initialized
  132. to non-default attributes. Any later attempt to lock such a mutex
  133. causes the implementation to branch to the ``slow path'' as if the
  134. mutex were unavailable; then, on the slow path, the implementation can
  135. do the ``real work'' to lock a non-default mutex. The underlying
  136. unlock operation is more complicated since the implementation never
  137. really wants to release the pre-lock on this kind of mutex. This
  138. illustrates that, depending on the hardware, there may be certain
  139. optimizations that can be used so that whatever mutex attributes are
  140. considered ``most frequently used'' can be processed most efficiently.
  141. .SS "Process Shared Memory and Synchronization"
  142. .P
  143. The existence of memory mapping functions in this volume of POSIX.1\(hy2017 leads to the
  144. possibility that an application may allocate the synchronization
  145. objects from this section in memory that is accessed by multiple
  146. processes (and therefore, by threads of multiple processes).
  147. .P
  148. In order to permit such usage, while at the same time keeping the usual
  149. case (that is, usage within a single process) efficient, a
  150. .IR process-shared
  151. option has been defined.
  152. .P
  153. If an implementation supports the _POSIX_THREAD_PROCESS_SHARED
  154. option, then the
  155. .IR process-shared
  156. attribute can be used to indicate that mutexes or condition variables
  157. may be accessed by threads of multiple processes.
  158. .P
  159. The default setting of PTHREAD_PROCESS_PRIVATE
  160. has been chosen for the
  161. .IR process-shared
  162. attribute so that the most efficient forms of these synchronization
  163. objects are created by default.
  164. .P
  165. Synchronization variables that are initialized with the
  166. PTHREAD_PROCESS_PRIVATE
  167. .IR process-shared
  168. attribute may only be operated on by threads in the process that
  169. initialized them. Synchronization variables that are initialized with
  170. the PTHREAD_PROCESS_SHARED
  171. .IR process-shared
  172. attribute may be operated on by any thread in any process that has
  173. access to it. In particular, these processes may exist beyond the
  174. lifetime of the initializing process. For example, the following code
  175. implements a simple counting semaphore in a mapped file that may be
  176. used by many processes.
  177. .sp
  178. .RS 4
  179. .nf
  180. /* sem.h */
  181. struct semaphore {
  182. pthread_mutex_t lock;
  183. pthread_cond_t nonzero;
  184. unsigned count;
  185. };
  186. typedef struct semaphore semaphore_t;
  187. .P
  188. semaphore_t *semaphore_create(char *semaphore_name);
  189. semaphore_t *semaphore_open(char *semaphore_name);
  190. void semaphore_post(semaphore_t *semap);
  191. void semaphore_wait(semaphore_t *semap);
  192. void semaphore_close(semaphore_t *semap);
  193. .P
  194. /* sem.c */
  195. #include <sys/types.h>
  196. #include <sys/stat.h>
  197. #include <sys/mman.h>
  198. #include <fcntl.h>
  199. #include <pthread.h>
  200. #include "sem.h"
  201. .P
  202. semaphore_t *
  203. semaphore_create(char *semaphore_name)
  204. {
  205. int fd;
  206. semaphore_t *semap;
  207. pthread_mutexattr_t psharedm;
  208. pthread_condattr_t psharedc;
  209. .P
  210. fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666);
  211. if (fd < 0)
  212. return (NULL);
  213. (void) ftruncate(fd, sizeof(semaphore_t));
  214. (void) pthread_mutexattr_init(&psharedm);
  215. (void) pthread_mutexattr_setpshared(&psharedm,
  216. PTHREAD_PROCESS_SHARED);
  217. (void) pthread_condattr_init(&psharedc);
  218. (void) pthread_condattr_setpshared(&psharedc,
  219. PTHREAD_PROCESS_SHARED);
  220. semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
  221. PROT_READ | PROT_WRITE, MAP_SHARED,
  222. fd, 0);
  223. close (fd);
  224. (void) pthread_mutex_init(&semap->lock, &psharedm);
  225. (void) pthread_cond_init(&semap->nonzero, &psharedc);
  226. semap->count = 0;
  227. return (semap);
  228. }
  229. .P
  230. semaphore_t *
  231. semaphore_open(char *semaphore_name)
  232. {
  233. int fd;
  234. semaphore_t *semap;
  235. .P
  236. fd = open(semaphore_name, O_RDWR, 0666);
  237. if (fd < 0)
  238. return (NULL);
  239. semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t),
  240. PROT_READ | PROT_WRITE, MAP_SHARED,
  241. fd, 0);
  242. close (fd);
  243. return (semap);
  244. }
  245. .P
  246. void
  247. semaphore_post(semaphore_t *semap)
  248. {
  249. pthread_mutex_lock(&semap->lock);
  250. if (semap->count == 0)
  251. pthread_cond_signal(&semapx->nonzero);
  252. semap->count++;
  253. pthread_mutex_unlock(&semap->lock);
  254. }
  255. .P
  256. void
  257. semaphore_wait(semaphore_t *semap)
  258. {
  259. pthread_mutex_lock(&semap->lock);
  260. while (semap->count == 0)
  261. pthread_cond_wait(&semap->nonzero, &semap->lock);
  262. semap->count--;
  263. pthread_mutex_unlock(&semap->lock);
  264. }
  265. .P
  266. void
  267. semaphore_close(semaphore_t *semap)
  268. {
  269. munmap((void *) semap, sizeof(semaphore_t));
  270. }
  271. .fi
  272. .P
  273. .RE
  274. .P
  275. The following code is for three separate processes that create, post,
  276. and wait on a semaphore in the file
  277. .BR /tmp/semaphore .
  278. Once the file is created, the post and wait programs increment and
  279. decrement the counting semaphore (waiting and waking as required) even
  280. though they did not initialize the semaphore.
  281. .sp
  282. .RS 4
  283. .nf
  284. /* create.c */
  285. #include "pthread.h"
  286. #include "sem.h"
  287. .P
  288. int
  289. main()
  290. {
  291. semaphore_t *semap;
  292. .P
  293. semap = semaphore_create("/tmp/semaphore");
  294. if (semap == NULL)
  295. exit(1);
  296. semaphore_close(semap);
  297. return (0);
  298. }
  299. .P
  300. /* post */
  301. #include "pthread.h"
  302. #include "sem.h"
  303. .P
  304. int
  305. main()
  306. {
  307. semaphore_t *semap;
  308. .P
  309. semap = semaphore_open("/tmp/semaphore");
  310. if (semap == NULL)
  311. exit(1);
  312. semaphore_post(semap);
  313. semaphore_close(semap);
  314. return (0);
  315. }
  316. .P
  317. /* wait */
  318. #include "pthread.h"
  319. #include "sem.h"
  320. .P
  321. int
  322. main()
  323. {
  324. semaphore_t *semap;
  325. .P
  326. semap = semaphore_open("/tmp/semaphore");
  327. if (semap == NULL)
  328. exit(1);
  329. semaphore_wait(semap);
  330. semaphore_close(semap);
  331. return (0);
  332. }
  333. .fi
  334. .P
  335. .RE
  336. .SH "FUTURE DIRECTIONS"
  337. None.
  338. .SH "SEE ALSO"
  339. .ad l
  340. .IR "\fIpthread_cond_destroy\fR\^(\|)",
  341. .IR "\fIpthread_create\fR\^(\|)",
  342. .IR "\fIpthread_mutex_destroy\fR\^(\|)"
  343. .ad b
  344. .P
  345. The Base Definitions volume of POSIX.1\(hy2017,
  346. .IR "\fB<pthread.h>\fP"
  347. .\"
  348. .SH COPYRIGHT
  349. Portions of this text are reprinted and reproduced in electronic form
  350. from IEEE Std 1003.1-2017, Standard for Information Technology
  351. -- Portable Operating System Interface (POSIX), The Open Group Base
  352. Specifications Issue 7, 2018 Edition,
  353. Copyright (C) 2018 by the Institute of
  354. Electrical and Electronics Engineers, Inc and The Open Group.
  355. In the event of any discrepancy between this version and the original IEEE and
  356. The Open Group Standard, the original IEEE and The Open Group Standard
  357. is the referee document. The original Standard can be obtained online at
  358. http://www.opengroup.org/unix/online.html .
  359. .PP
  360. Any typographical or formatting errors that appear
  361. in this page are most likely
  362. to have been introduced during the conversion of the source files to
  363. man page format. To report such errors, see
  364. https://www.kernel.org/doc/man-pages/reporting_bugs.html .