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_mutex_destroy.3p (15973B)


  1. '\" et
  2. .TH PTHREAD_MUTEX_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_mutex_destroy,
  12. pthread_mutex_init
  13. \(em destroy and initialize a mutex
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pthread.h>
  18. .P
  19. int pthread_mutex_destroy(pthread_mutex_t *\fImutex\fP);
  20. int pthread_mutex_init(pthread_mutex_t *restrict \fImutex\fP,
  21. const pthread_mutexattr_t *restrict \fIattr\fP);
  22. pthread_mutex_t \fImutex\fP = PTHREAD_MUTEX_INITIALIZER;
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIpthread_mutex_destroy\fR()
  27. function shall destroy the mutex object referenced by
  28. .IR mutex ;
  29. the mutex object becomes, in effect, uninitialized. An implementation
  30. may cause
  31. \fIpthread_mutex_destroy\fR()
  32. to set the object referenced by
  33. .IR mutex
  34. to an invalid value.
  35. .P
  36. A destroyed mutex object can be reinitialized using
  37. \fIpthread_mutex_init\fR();
  38. the results of otherwise referencing the object after it has been
  39. destroyed are undefined.
  40. .P
  41. It shall be safe to destroy an initialized mutex that is unlocked.
  42. Attempting to destroy a locked mutex, or a mutex that another thread
  43. is attempting to lock, or a mutex that is being used in a
  44. \fIpthread_cond_timedwait\fR()
  45. or
  46. \fIpthread_cond_wait\fR()
  47. call by another thread, results in undefined behavior.
  48. .P
  49. The
  50. \fIpthread_mutex_init\fR()
  51. function shall initialize the mutex referenced by
  52. .IR mutex
  53. with attributes specified by
  54. .IR attr .
  55. If
  56. .IR attr
  57. is NULL, the default mutex attributes are used; the effect shall be the
  58. same as passing the address of a default mutex attributes object. Upon
  59. successful initialization, the state of the mutex becomes initialized
  60. and unlocked.
  61. .P
  62. See
  63. .IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings"
  64. for further requirements.
  65. .P
  66. Attempting to initialize an already initialized mutex results in
  67. undefined behavior.
  68. .P
  69. In cases where default mutex attributes are appropriate, the macro
  70. PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes. The
  71. effect shall be equivalent to dynamic initialization by a call to
  72. \fIpthread_mutex_init\fR()
  73. with parameter
  74. .IR attr
  75. specified as NULL, except that no error checks are performed.
  76. .P
  77. The behavior is undefined if the value specified by the
  78. .IR mutex
  79. argument to
  80. \fIpthread_mutex_destroy\fR()
  81. does not refer to an initialized mutex.
  82. .P
  83. The behavior is undefined if the value specified by the
  84. .IR attr
  85. argument to
  86. \fIpthread_mutex_init\fR()
  87. does not refer to an initialized mutex attributes object.
  88. .SH "RETURN VALUE"
  89. If successful, the
  90. \fIpthread_mutex_destroy\fR()
  91. and
  92. \fIpthread_mutex_init\fR()
  93. functions shall return zero; otherwise, an error number shall be
  94. returned to indicate the error.
  95. .SH ERRORS
  96. The
  97. \fIpthread_mutex_init\fR()
  98. function shall fail if:
  99. .TP
  100. .BR EAGAIN
  101. The system lacked the necessary resources (other than memory) to
  102. initialize another mutex.
  103. .TP
  104. .BR ENOMEM
  105. Insufficient memory exists to initialize the mutex.
  106. .TP
  107. .BR EPERM
  108. The caller does not have the privilege to perform the operation.
  109. .br
  110. .P
  111. The
  112. \fIpthread_mutex_init\fR()
  113. function may fail if:
  114. .TP
  115. .BR EINVAL
  116. The attributes object referenced by
  117. .IR attr
  118. has the robust mutex attribute set without the process-shared attribute
  119. being set.
  120. .P
  121. These functions shall not return an error code of
  122. .BR [EINTR] .
  123. .LP
  124. .IR "The following sections are informative."
  125. .SH EXAMPLES
  126. None.
  127. .SH "APPLICATION USAGE"
  128. None.
  129. .SH RATIONALE
  130. If an implementation detects that the value specified by the
  131. .IR mutex
  132. argument to
  133. \fIpthread_mutex_destroy\fR()
  134. does not refer to an initialized mutex, it is recommended that the
  135. function should fail and report an
  136. .BR [EINVAL]
  137. error.
  138. .P
  139. If an implementation detects that the value specified by the
  140. .IR mutex
  141. argument to
  142. \fIpthread_mutex_destroy\fR()
  143. or
  144. \fIpthread_mutex_init\fR()
  145. refers to a locked mutex or a mutex that is referenced (for example,
  146. while being used in a
  147. \fIpthread_cond_timedwait\fR()
  148. or
  149. \fIpthread_cond_wait\fR())
  150. by another thread, or detects that the value specified by the
  151. .IR mutex
  152. argument to
  153. \fIpthread_mutex_init\fR()
  154. refers to an already initialized mutex, it is recommended that the
  155. function should fail and report an
  156. .BR [EBUSY]
  157. error.
  158. .P
  159. If an implementation detects that the value specified by the
  160. .IR attr
  161. argument to
  162. \fIpthread_mutex_init\fR()
  163. does not refer to an initialized mutex attributes object, it is
  164. recommended that the function should fail and report an
  165. .BR [EINVAL]
  166. error.
  167. .SS "Alternate Implementations Possible"
  168. .P
  169. This volume of POSIX.1\(hy2017 supports several alternative implementations of mutexes.
  170. An implementation may store the lock directly in the object of type
  171. .BR pthread_mutex_t .
  172. Alternatively, an implementation may store the lock in the heap and
  173. merely store a pointer, handle, or unique ID in the mutex object.
  174. Either implementation has advantages or may be required on certain
  175. hardware configurations. So that portable code can be written that is
  176. invariant to this choice, this volume of POSIX.1\(hy2017 does not define assignment or
  177. equality for this type, and it uses the term ``initialize'' to
  178. reinforce the (more restrictive) notion that the lock may actually
  179. reside in the mutex object itself.
  180. .P
  181. Note that this precludes an over-specification of the type of the mutex
  182. or condition variable and motivates the opaqueness of the type.
  183. .P
  184. An implementation is permitted, but not required, to have
  185. \fIpthread_mutex_destroy\fR()
  186. store an illegal value into the mutex. This may help detect erroneous
  187. programs that try to lock (or otherwise reference) a mutex that has
  188. already been destroyed.
  189. .SS "Tradeoff Between Error Checks and Performance Supported"
  190. .P
  191. Many error conditions that can occur are not required to be detected by
  192. the implementation in order to let implementations trade off performance
  193. \fIversus\fR degree of error checking according to the needs of their
  194. specific applications and execution environment. As a general rule,
  195. conditions caused by the system (such as insufficient memory) are required
  196. to be detected, but conditions caused by an erroneously coded application
  197. (such as failing to provide adequate synchronization to prevent a mutex
  198. from being deleted while in use) are specified to result in undefined
  199. behavior.
  200. .P
  201. A wide range of implementations is thus made possible. For example, an
  202. implementation intended for application debugging may implement all of
  203. the error checks, but an implementation running a single, provably
  204. correct application under very tight performance constraints in an
  205. embedded computer might implement minimal checks. An implementation
  206. might even be provided in two versions, similar to the options that
  207. compilers provide: a full-checking, but slower version; and a
  208. limited-checking, but faster version. To forbid this optionality would
  209. be a disservice to users.
  210. .P
  211. By carefully limiting the use of ``undefined behavior'' only to things
  212. that an erroneous (badly coded) application might do, and by defining
  213. that resource-not-available errors are mandatory, this volume of POSIX.1\(hy2017 ensures that
  214. a fully-conforming application is portable across the full range of
  215. implementations, while not forcing all implementations to add overhead
  216. to check for numerous things that a correct program never does. When the
  217. behavior is undefined, no error number is specified to be returned on
  218. implementations that do detect the condition. This is because undefined
  219. behavior means \fIanything\fR can happen, which includes returning
  220. with any value (which might happen to be a valid, but different, error
  221. number). However, since the error number might be useful to application
  222. developers when diagnosing problems during application development, a
  223. recommendation is made in rationale that implementors should return a
  224. particular error number if their implementation does detect the condition.
  225. .SS "Why No Limits are Defined"
  226. .P
  227. Defining symbols for the maximum number of mutexes and condition
  228. variables was considered but rejected because the number of these
  229. objects may change dynamically. Furthermore, many implementations
  230. place these objects into application memory; thus, there is no explicit
  231. maximum.
  232. .SS "Static Initializers for Mutexes and Condition Variables"
  233. .P
  234. Providing for static initialization of statically allocated
  235. synchronization objects allows modules with private static
  236. synchronization variables to avoid runtime initialization tests and
  237. overhead. Furthermore, it simplifies the coding of self-initializing
  238. modules. Such modules are common in C libraries, where for various
  239. reasons the design calls for self-initialization instead of requiring
  240. an explicit module initialization function to be called. An example
  241. use of static initialization follows.
  242. .P
  243. Without static initialization, a self-initializing routine
  244. \fIfoo\fR()
  245. might look as follows:
  246. .sp
  247. .RS 4
  248. .nf
  249. static pthread_once_t foo_once = PTHREAD_ONCE_INIT;
  250. static pthread_mutex_t foo_mutex;
  251. .P
  252. void foo_init()
  253. {
  254. pthread_mutex_init(&foo_mutex, NULL);
  255. }
  256. .P
  257. void foo()
  258. {
  259. pthread_once(&foo_once, foo_init);
  260. pthread_mutex_lock(&foo_mutex);
  261. /* Do work. */
  262. pthread_mutex_unlock(&foo_mutex);
  263. }
  264. .fi
  265. .P
  266. .RE
  267. .P
  268. With static initialization, the same routine could be coded as
  269. follows:
  270. .sp
  271. .RS 4
  272. .nf
  273. static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER;
  274. .P
  275. void foo()
  276. {
  277. pthread_mutex_lock(&foo_mutex);
  278. /* Do work. */
  279. pthread_mutex_unlock(&foo_mutex);
  280. }
  281. .fi
  282. .P
  283. .RE
  284. .P
  285. Note that the static initialization both eliminates the need for the
  286. initialization test inside
  287. \fIpthread_once\fR()
  288. and the fetch of &\fIfoo_mutex\fP to learn the address to be passed to
  289. \fIpthread_mutex_lock\fR()
  290. or
  291. \fIpthread_mutex_unlock\fR().
  292. .P
  293. Thus, the C code written to initialize static objects is simpler on all
  294. systems and is also faster on a large class of systems; those where the
  295. (entire) synchronization object can be stored in application memory.
  296. .P
  297. Yet the locking performance question is likely to be raised for
  298. machines that require mutexes to be allocated out of special memory.
  299. Such machines actually have to have mutexes and possibly condition
  300. variables contain pointers to the actual hardware locks. For static
  301. initialization to work on such machines,
  302. \fIpthread_mutex_lock\fR()
  303. also has to test whether or not the pointer to the actual lock has been
  304. allocated. If it has not,
  305. \fIpthread_mutex_lock\fR()
  306. has to initialize it before use. The reservation of such resources can
  307. be made when the program is loaded, and hence return codes have not
  308. been added to mutex locking and condition variable waiting to indicate
  309. failure to complete initialization.
  310. .P
  311. This runtime test in
  312. \fIpthread_mutex_lock\fR()
  313. would at first seem to be extra work; an extra test is required to see
  314. whether the pointer has been initialized. On most machines this would
  315. actually be implemented as a fetch of the pointer, testing the pointer
  316. against zero, and then using the pointer if it has already been
  317. initialized. While the test might seem to add extra work, the extra
  318. effort of testing a register is usually negligible since no extra
  319. memory references are actually done. As more and more machines provide
  320. caches, the real expenses are memory references, not instructions
  321. executed.
  322. .P
  323. Alternatively, depending on the machine architecture, there are often
  324. ways to eliminate
  325. .IR all
  326. overhead in the most important case: on the lock operations that occur
  327. .IR after
  328. the lock has been initialized. This can be done by shifting more
  329. overhead to the less frequent operation: initialization. Since
  330. out-of-line mutex allocation also means that an address has to be
  331. dereferenced to find the actual lock, one technique that is widely
  332. applicable is to have static initialization store a bogus value for
  333. that address; in particular, an address that causes a machine fault to
  334. occur. When such a fault occurs upon the first attempt to lock such a
  335. mutex, validity checks can be done, and then the correct address for
  336. the actual lock can be filled in. Subsequent lock operations incur no
  337. extra overhead since they do not ``fault''. This is merely one
  338. technique that can be used to support static initialization, while not
  339. adversely affecting the performance of lock acquisition. No doubt
  340. there are other techniques that are highly machine-dependent.
  341. .P
  342. The locking overhead for machines doing out-of-line mutex allocation is
  343. thus similar for modules being implicitly initialized, where it is
  344. improved for those doing mutex allocation entirely inline. The inline
  345. case is thus made much faster, and the out-of-line case is not
  346. significantly worse.
  347. .P
  348. Besides the issue of locking performance for such machines, a concern
  349. is raised that it is possible that threads would serialize contending
  350. for initialization locks when attempting to finish initializing
  351. statically allocated mutexes. (Such finishing would typically involve
  352. taking an internal lock, allocating a structure, storing a pointer to
  353. the structure in the mutex, and releasing the internal lock.) First,
  354. many implementations would reduce such serialization by hashing on the
  355. mutex address. Second, such serialization can only occur a bounded
  356. number of times. In particular, it can happen at most as many times as
  357. there are statically allocated synchronization objects. Dynamically
  358. allocated objects would still be initialized via
  359. \fIpthread_mutex_init\fR()
  360. or
  361. \fIpthread_cond_init\fR().
  362. .P
  363. Finally, if none of the above optimization techniques for out-of-line
  364. allocation yields sufficient performance for an application on some
  365. implementation, the application can avoid static initialization
  366. altogether by explicitly initializing all synchronization objects with
  367. the corresponding
  368. .IR pthread_*_init (\|)
  369. functions, which are supported by all implementations. An
  370. implementation can also document the tradeoffs and advise which
  371. initialization technique is more efficient for that particular
  372. implementation.
  373. .SS "Destroying Mutexes"
  374. .P
  375. A mutex can be destroyed immediately after it is unlocked. However,
  376. since attempting to destroy a locked mutex, or a mutex that another
  377. thread is attempting to lock, or a mutex that is being used in a
  378. \fIpthread_cond_timedwait\fR()
  379. or
  380. \fIpthread_cond_wait\fR()
  381. call by another thread, results in undefined behavior, care must be
  382. taken to ensure that no other thread may be referencing the mutex.
  383. .SS "Robust Mutexes"
  384. .P
  385. Implementations are required to provide robust mutexes
  386. for mutexes with the process-shared attribute set to
  387. PTHREAD_PROCESS_SHARED. Implementations are allowed, but not required,
  388. to provide robust mutexes when the process-shared attribute is set to
  389. PTHREAD_PROCESS_PRIVATE.
  390. .SH "FUTURE DIRECTIONS"
  391. None.
  392. .SH "SEE ALSO"
  393. .ad l
  394. .IR "\fIpthread_mutex_getprioceiling\fR\^(\|)",
  395. .IR "\fIpthread_mutexattr_getrobust\fR\^(\|)",
  396. .IR "\fIpthread_mutex_lock\fR\^(\|)",
  397. .IR "\fIpthread_mutex_timedlock\fR\^(\|)",
  398. .IR "\fIpthread_mutexattr_getpshared\fR\^(\|)"
  399. .ad b
  400. .P
  401. The Base Definitions volume of POSIX.1\(hy2017,
  402. .IR "\fB<pthread.h>\fP"
  403. .\"
  404. .SH COPYRIGHT
  405. Portions of this text are reprinted and reproduced in electronic form
  406. from IEEE Std 1003.1-2017, Standard for Information Technology
  407. -- Portable Operating System Interface (POSIX), The Open Group Base
  408. Specifications Issue 7, 2018 Edition,
  409. Copyright (C) 2018 by the Institute of
  410. Electrical and Electronics Engineers, Inc and The Open Group.
  411. In the event of any discrepancy between this version and the original IEEE and
  412. The Open Group Standard, the original IEEE and The Open Group Standard
  413. is the referee document. The original Standard can be obtained online at
  414. http://www.opengroup.org/unix/online.html .
  415. .PP
  416. Any typographical or formatting errors that appear
  417. in this page are most likely
  418. to have been introduced during the conversion of the source files to
  419. man page format. To report such errors, see
  420. https://www.kernel.org/doc/man-pages/reporting_bugs.html .