Provided by: manpages-posix-dev_2013a-2_all 
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of
this interface may differ (consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on Linux.
NAME
pthread_mutex_destroy, pthread_mutex_init — destroy and initialize a mutex
SYNOPSIS
#include <pthread.h>
int pthread_mutex_destroy(pthread_mutex_t *mutex);
int pthread_mutex_init(pthread_mutex_t *restrict mutex,
const pthread_mutexattr_t *restrict attr);
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
DESCRIPTION
The pthread_mutex_destroy() function shall destroy the mutex object referenced by mutex;
the mutex object becomes, in effect, uninitialized. An implementation may cause
pthread_mutex_destroy() to set the object referenced by mutex to an invalid value.
A destroyed mutex object can be reinitialized using pthread_mutex_init(); the results of
otherwise referencing the object after it has been destroyed are undefined.
It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy
a locked mutex or a mutex that is referenced (for example, while being used in a
pthread_cond_timedwait() or pthread_cond_wait()) by another thread results in undefined
behavior.
The pthread_mutex_init() function shall initialize the mutex referenced by mutex with
attributes specified by attr. If attr is NULL, the default mutex attributes are used; the
effect shall be the same as passing the address of a default mutex attributes object. Upon
successful initialization, the state of the mutex becomes initialized and unlocked.
Only mutex itself may be used for performing synchronization. The result of referring to
copies of mutex in calls to pthread_mutex_lock(), pthread_mutex_trylock(),
pthread_mutex_unlock(), and pthread_mutex_destroy() is undefined.
Attempting to initialize an already initialized mutex results in undefined behavior.
In cases where default mutex attributes are appropriate, the macro
PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes. The effect shall be
equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr
specified as NULL, except that no error checks are performed.
The behavior is undefined if the value specified by the mutex argument to
pthread_mutex_destroy() does not refer to an initialized mutex.
The behavior is undefined if the value specified by the attr argument to
pthread_mutex_init() does not refer to an initialized mutex attributes object.
RETURN VALUE
If successful, the pthread_mutex_destroy() and pthread_mutex_init() functions shall return
zero; otherwise, an error number shall be returned to indicate the error.
ERRORS
The pthread_mutex_init() function shall fail if:
EAGAIN The system lacked the necessary resources (other than memory) to initialize another
mutex.
ENOMEM Insufficient memory exists to initialize the mutex.
EPERM The caller does not have the privilege to perform the operation.
The pthread_mutex_init() function may fail if:
EINVAL The attributes object referenced by attr has the robust mutex attribute set without
the process-shared attribute being set.
These functions shall not return an error code of [EINTR].
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
None.
RATIONALE
If an implementation detects that the value specified by the mutex argument to
pthread_mutex_destroy() does not refer to an initialized mutex, it is recommended that the
function should fail and report an [EINVAL] error.
If an implementation detects that the value specified by the mutex argument to
pthread_mutex_destroy() or pthread_mutex_init() refers to a locked mutex or a mutex that
is referenced (for example, while being used in a pthread_cond_timedwait() or
pthread_cond_wait()) by another thread, or detects that the value specified by the mutex
argument to pthread_mutex_init() refers to an already initialized mutex, it is recommended
that the function should fail and report an [EBUSY] error.
If an implementation detects that the value specified by the attr argument to
pthread_mutex_init() does not refer to an initialized mutex attributes object, it is
recommended that the function should fail and report an [EINVAL] error.
Alternate Implementations Possible
This volume of POSIX.1‐2008 supports several alternative implementations of mutexes. An
implementation may store the lock directly in the object of type pthread_mutex_t.
Alternatively, an implementation may store the lock in the heap and merely store a
pointer, handle, or unique ID in the mutex object. Either implementation has advantages
or may be required on certain hardware configurations. So that portable code can be
written that is invariant to this choice, this volume of POSIX.1‐2008 does not define
assignment or equality for this type, and it uses the term ``initialize'' to reinforce the
(more restrictive) notion that the lock may actually reside in the mutex object itself.
Note that this precludes an over-specification of the type of the mutex or condition
variable and motivates the opaqueness of the type.
An implementation is permitted, but not required, to have pthread_mutex_destroy() store an
illegal value into the mutex. This may help detect erroneous programs that try to lock (or
otherwise reference) a mutex that has already been destroyed.
Tradeoff Between Error Checks and Performance Supported
Many error conditions that can occur are not required to be detected by the implementation
in order to let implementations trade off performance versus degree of error checking
according to the needs of their specific applications and execution environment. As a
general rule, conditions caused by the system (such as insufficient memory) are required
to be detected, but conditions caused by an erroneously coded application (such as failing
to provide adequate synchronization to prevent a mutex from being deleted while in use)
are specified to result in undefined behavior.
A wide range of implementations is thus made possible. For example, an implementation
intended for application debugging may implement all of the error checks, but an
implementation running a single, provably correct application under very tight performance
constraints in an embedded computer might implement minimal checks. An implementation
might even be provided in two versions, similar to the options that compilers provide: a
full-checking, but slower version; and a limited-checking, but faster version. To forbid
this optionality would be a disservice to users.
By carefully limiting the use of ``undefined behavior'' only to things that an erroneous
(badly coded) application might do, and by defining that resource-not-available errors are
mandatory, this volume of POSIX.1‐2008 ensures that a fully-conforming application is
portable across the full range of implementations, while not forcing all implementations
to add overhead to check for numerous things that a correct program never does. When the
behavior is undefined, no error number is specified to be returned on implementations that
do detect the condition. This is because undefined behavior means anything can happen,
which includes returning with any value (which might happen to be a valid, but different,
error number). However, since the error number might be useful to application developers
when diagnosing problems during application development, a recommendation is made in
rationale that implementors should return a particular error number if their
implementation does detect the condition.
Why No Limits are Defined
Defining symbols for the maximum number of mutexes and condition variables was considered
but rejected because the number of these objects may change dynamically. Furthermore, many
implementations place these objects into application memory; thus, there is no explicit
maximum.
Static Initializers for Mutexes and Condition Variables
Providing for static initialization of statically allocated synchronization objects allows
modules with private static synchronization variables to avoid runtime initialization
tests and overhead. Furthermore, it simplifies the coding of self-initializing modules.
Such modules are common in C libraries, where for various reasons the design calls for
self-initialization instead of requiring an explicit module initialization function to be
called. An example use of static initialization follows.
Without static initialization, a self-initializing routine foo() might look as follows:
static pthread_once_t foo_once = PTHREAD_ONCE_INIT;
static pthread_mutex_t foo_mutex;
void foo_init()
{
pthread_mutex_init(&foo_mutex, NULL);
}
void foo()
{
pthread_once(&foo_once, foo_init);
pthread_mutex_lock(&foo_mutex);
/* Do work. */
pthread_mutex_unlock(&foo_mutex);
}
With static initialization, the same routine could be coded as follows:
static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER;
void foo()
{
pthread_mutex_lock(&foo_mutex);
/* Do work. */
pthread_mutex_unlock(&foo_mutex);
}
Note that the static initialization both eliminates the need for the initialization test
inside pthread_once() and the fetch of &foo_mutex to learn the address to be passed to
pthread_mutex_lock() or pthread_mutex_unlock().
Thus, the C code written to initialize static objects is simpler on all systems and is
also faster on a large class of systems; those where the (entire) synchronization object
can be stored in application memory.
Yet the locking performance question is likely to be raised for machines that require
mutexes to be allocated out of special memory. Such machines actually have to have
mutexes and possibly condition variables contain pointers to the actual hardware locks.
For static initialization to work on such machines, pthread_mutex_lock() also has to test
whether or not the pointer to the actual lock has been allocated. If it has not,
pthread_mutex_lock() has to initialize it before use. The reservation of such resources
can be made when the program is loaded, and hence return codes have not been added to
mutex locking and condition variable waiting to indicate failure to complete
initialization.
This runtime test in pthread_mutex_lock() would at first seem to be extra work; an extra
test is required to see whether the pointer has been initialized. On most machines this
would actually be implemented as a fetch of the pointer, testing the pointer against zero,
and then using the pointer if it has already been initialized. While the test might seem
to add extra work, the extra effort of testing a register is usually negligible since no
extra memory references are actually done. As more and more machines provide caches, the
real expenses are memory references, not instructions executed.
Alternatively, depending on the machine architecture, there are often ways to eliminate
all overhead in the most important case: on the lock operations that occur after the lock
has been initialized. This can be done by shifting more overhead to the less frequent
operation: initialization. Since out-of-line mutex allocation also means that an address
has to be dereferenced to find the actual lock, one technique that is widely applicable is
to have static initialization store a bogus value for that address; in particular, an
address that causes a machine fault to occur. When such a fault occurs upon the first
attempt to lock such a mutex, validity checks can be done, and then the correct address
for the actual lock can be filled in. Subsequent lock operations incur no extra overhead
since they do not ``fault''. This is merely one technique that can be used to support
static initialization, while not adversely affecting the performance of lock acquisition.
No doubt there are other techniques that are highly machine-dependent.
The locking overhead for machines doing out-of-line mutex allocation is thus similar for
modules being implicitly initialized, where it is improved for those doing mutex
allocation entirely inline. The inline case is thus made much faster, and the out-of-line
case is not significantly worse.
Besides the issue of locking performance for such machines, a concern is raised that it is
possible that threads would serialize contending for initialization locks when attempting
to finish initializing statically allocated mutexes. (Such finishing would typically
involve taking an internal lock, allocating a structure, storing a pointer to the
structure in the mutex, and releasing the internal lock.) First, many implementations
would reduce such serialization by hashing on the mutex address. Second, such
serialization can only occur a bounded number of times. In particular, it can happen at
most as many times as there are statically allocated synchronization objects. Dynamically
allocated objects would still be initialized via pthread_mutex_init() or
pthread_cond_init().
Finally, if none of the above optimization techniques for out-of-line allocation yields
sufficient performance for an application on some implementation, the application can
avoid static initialization altogether by explicitly initializing all synchronization
objects with the corresponding pthread_*_init() functions, which are supported by all
implementations. An implementation can also document the tradeoffs and advise which
initialization technique is more efficient for that particular implementation.
Destroying Mutexes
A mutex can be destroyed immediately after it is unlocked. For example, consider the
following code:
struct obj {
pthread_mutex_t om;
int refcnt;
...
};
obj_done(struct obj *op)
{
pthread_mutex_lock(&op->om);
if (--op->refcnt == 0) {
pthread_mutex_unlock(&op->om);
(A) pthread_mutex_destroy(&op->om);
(B) free(op);
} else
(C) pthread_mutex_unlock(&op->om);
}
In this case obj is reference counted and obj_done() is called whenever a reference to the
object is dropped. Implementations are required to allow an object to be destroyed and
freed and potentially unmapped (for example, lines A and B) immediately after the object
is unlocked (line C).
Robust Mutexes
Implementations are required to provide robust mutexes for mutexes with the process-shared
attribute set to PTHREAD_PROCESS_SHARED. Implementations are allowed, but not required, to
provide robust mutexes when the process-shared attribute is set to
PTHREAD_PROCESS_PRIVATE.
FUTURE DIRECTIONS
None.
SEE ALSO
pthread_mutex_getprioceiling(), pthread_mutexattr_getrobust(), pthread_mutex_lock(),
pthread_mutex_timedlock(), pthread_mutexattr_getpshared()
The Base Definitions volume of POSIX.1‐2008, <pthread.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the event of any
discrepancy between this version and the original IEEE and The Open Group Standard, the
original IEEE and The Open Group Standard is the referee document. The original Standard
can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are most likely to have
been introduced during the conversion of the source files to man page format. To report
such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .