pthread_mutexattr_destroy.3p (11054B)
- '\" et
- .TH PTHREAD_MUTEXATTR_DESTROY "3P" 2017 "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\(hy2017 without changing the existing functions. Thus, they
- provide for future extensibility of this volume of POSIX.1\(hy2017 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\(hy2017. 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\(hy2017 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
- /* 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
- .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
- /* 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
- .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\(hy2017,
- .IR "\fB<pthread.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- 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.opengroup.org/unix/online.html .
- .PP
- 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 .