diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p b/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p new file mode 100644 index 0000000..1c6bdc9 --- /dev/null +++ b/man-pages-posix-2013/man3p/pthread_mutexattr_destroy.3p @@ -0,0 +1,364 @@ +'\" et +.TH PTHREAD_MUTEXATTR_DESTROY "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH 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. + +.SH NAME +pthread_mutexattr_destroy, +pthread_mutexattr_init +\(em destroy and initialize the mutex attributes object +.SH SYNOPSIS +.LP +.nf +#include <pthread.h> +.P +int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP); +int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_destroy\fR() +function shall destroy a mutex attributes object; the object becomes, +in effect, uninitialized. An implementation may cause +\fIpthread_mutexattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_mutexattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_mutexattr_init\fR() +function shall initialize a mutex attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_mutexattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a mutex attributes object has been used to initialize one or more +mutexes, any function affecting the attributes object (including +destruction) shall not affect any previously initialized mutexes. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_mutexattr_destroy\fR() +and +\fIpthread_mutexattr_init\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the mutex attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See +.IR "\fIpthread_attr_destroy\fR\^(\|)" +for a general explanation of attributes. Attributes objects allow +implementations to experiment with useful extensions and permit +extension of this volume of POSIX.1\(hy2008 without changing the existing functions. Thus, they +provide for future extensibility of this volume of POSIX.1\(hy2008 and reduce the temptation to +standardize prematurely on semantics that are not yet widely +implemented or understood. +.P +Examples of possible additional mutex attributes that have been +discussed are +.IR spin_only , +.IR limited_spin , +.IR no_spin , +.IR recursive , +and +.IR metered . +(To explain what the latter attributes might mean: recursive mutexes +would allow for multiple re-locking by the current owner; metered +mutexes would transparently keep records of queue length, wait time, +and so on.) Since there is not yet wide agreement on the usefulness of +these resulting from shared implementation and usage experience, they +are not yet specified in this volume of POSIX.1\(hy2008. Mutex attributes objects, +however, make it possible to test out these concepts for possible +standardization at a later time. +.SS "Mutex Attributes and Performance" +.P +Care has been taken to ensure that the default values of the mutex +attributes have been defined such that mutexes initialized with the +defaults have simple enough semantics so that the locking and unlocking +can be done with the equivalent of a test-and-set instruction (plus +possibly a few other basic instructions). +.P +There is at least one implementation method that can be used to reduce +the cost of testing at lock-time if a mutex has non-default +attributes. One such method that an implementation can employ (and +this can be made fully transparent to fully conforming POSIX +applications) is to secretly pre-lock any mutexes that are initialized +to non-default attributes. Any later attempt to lock such a mutex +causes the implementation to branch to the ``slow path'' as if the +mutex were unavailable; then, on the slow path, the implementation can +do the ``real work'' to lock a non-default mutex. The underlying +unlock operation is more complicated since the implementation never +really wants to release the pre-lock on this kind of mutex. This +illustrates that, depending on the hardware, there may be certain +optimizations that can be used so that whatever mutex attributes are +considered ``most frequently used'' can be processed most efficiently. +.SS "Process Shared Memory and Synchronization" +.P +The existence of memory mapping functions in this volume of POSIX.1\(hy2008 leads to the +possibility that an application may allocate the synchronization +objects from this section in memory that is accessed by multiple +processes (and therefore, by threads of multiple processes). +.P +In order to permit such usage, while at the same time keeping the usual +case (that is, usage within a single process) efficient, a +.IR process-shared +option has been defined. +.P +If an implementation supports the _POSIX_THREAD_PROCESS_SHARED +option, then the +.IR process-shared +attribute can be used to indicate that mutexes or condition variables +may be accessed by threads of multiple processes. +.P +The default setting of PTHREAD_PROCESS_PRIVATE +has been chosen for the +.IR process-shared +attribute so that the most efficient forms of these synchronization +objects are created by default. +.P +Synchronization variables that are initialized with the +PTHREAD_PROCESS_PRIVATE +.IR process-shared +attribute may only be operated on by threads in the process that +initialized them. Synchronization variables that are initialized with +the PTHREAD_PROCESS_SHARED +.IR process-shared +attribute may be operated on by any thread in any process that has +access to it. In particular, these processes may exist beyond the +lifetime of the initializing process. For example, the following code +implements a simple counting semaphore in a mapped file that may be +used by many processes. +.sp +.RS 4 +.nf +\fB +/* sem.h */ +struct semaphore { + pthread_mutex_t lock; + pthread_cond_t nonzero; + unsigned count; +}; +typedef struct semaphore semaphore_t; +.P +semaphore_t *semaphore_create(char *semaphore_name); +semaphore_t *semaphore_open(char *semaphore_name); +void semaphore_post(semaphore_t *semap); +void semaphore_wait(semaphore_t *semap); +void semaphore_close(semaphore_t *semap); +.P +/* sem.c */ +#include <sys/types.h> +#include <sys/stat.h> +#include <sys/mman.h> +#include <fcntl.h> +#include <pthread.h> +#include "sem.h" +.P +semaphore_t * +semaphore_create(char *semaphore_name) +{ +int fd; + semaphore_t *semap; + pthread_mutexattr_t psharedm; + pthread_condattr_t psharedc; +.P + fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666); + if (fd < 0) + return (NULL); + (void) ftruncate(fd, sizeof(semaphore_t)); + (void) pthread_mutexattr_init(&psharedm); + (void) pthread_mutexattr_setpshared(&psharedm, + PTHREAD_PROCESS_SHARED); + (void) pthread_condattr_init(&psharedc); + (void) pthread_condattr_setpshared(&psharedc, + PTHREAD_PROCESS_SHARED); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + (void) pthread_mutex_init(&semap->lock, &psharedm); + (void) pthread_cond_init(&semap->nonzero, &psharedc); + semap->count = 0; + return (semap); +} +.P +semaphore_t * +semaphore_open(char *semaphore_name) +{ + int fd; + semaphore_t *semap; +.P + fd = open(semaphore_name, O_RDWR, 0666); + if (fd < 0) + return (NULL); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + return (semap); +} +.P +void +semaphore_post(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + if (semap->count == 0) + pthread_cond_signal(&semapx->nonzero); + semap->count++; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_wait(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + while (semap->count == 0) + pthread_cond_wait(&semap->nonzero, &semap->lock); + semap->count-\|-; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_close(semaphore_t *semap) +{ + munmap((void *) semap, sizeof(semaphore_t)); +} +.fi \fR +.P +.RE +.P +The following code is for three separate processes that create, post, +and wait on a semaphore in the file +.BR /tmp/semaphore . +Once the file is created, the post and wait programs increment and +decrement the counting semaphore (waiting and waking as required) even +though they did not initialize the semaphore. +.sp +.RS 4 +.nf +\fB +/* create.c */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_create("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_close(semap); + return (0); +} +.P +/* post */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_post(semap); + semaphore_close(semap); + return (0); +} +.P +/* wait */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_wait(semap); + semaphore_close(semap); + return (0); +} +.fi \fR +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB<pthread.h>\fP" +.SH 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 . |