-.\" $NetBSD: pthread_mutexattr.3,v 1.3 2003/07/04 08:36:06 wiz Exp $
+.\" $NetBSD: pthread_mutexattr.3,v 1.11 2010/07/08 22:46:34 jruoho Exp $
.\"
-.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2002, 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. Neither the name of The NetBSD Foundation nor the names of its
-.\" contributors may be used to endorse or promote products derived
-.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/lib/libpthread/man/pthread_mutexattr.3,v 1.8 2002/09/16 19:29:29 mini Exp $
-.Dd January 30, 2003
+.\" $FreeBSD$
+.Dd July 9, 2010
.Dt PTHREAD_MUTEXATTR 3
.Os
.Sh NAME
-.Nm pthread_mutexattr_destroy ,
-.Nm pthread_mutexattr_getprioceiling ,
-.Nm pthread_mutexattr_getprotocol ,
-.Nm pthread_mutexattr_gettype ,
.Nm pthread_mutexattr_init ,
+.Nm pthread_mutexattr_destroy ,
.Nm pthread_mutexattr_setprioceiling ,
+.Nm pthread_mutexattr_getprioceiling ,
.Nm pthread_mutexattr_setprotocol ,
-.Nm pthread_mutexattr_settype
+.Nm pthread_mutexattr_getprotocol ,
+.Nm pthread_mutexattr_settype ,
+.Nm pthread_mutexattr_gettype
.Nd mutex attribute operations
.Sh SYNOPSIS
-.Fd #include <pthread.h>
+.In pthread.h
+.Ft int
+.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr"
+.Ft int
+.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr"
.Ft int
-.Fo pthread_mutexattr_destroy
-.Fa "pthread_mutexattr_t *attr"
-.Fc
+.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int prioceiling"
.Ft int
-.Fo pthread_mutexattr_getprioceiling
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict prioceiling"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_getprioceiling
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict prioceiling"
-.\" .Fc
+.Fn pthread_mutexattr_getprioceiling "pthread_mutexattr_t *attr" "int *prioceiling"
.Ft int
-.Fo pthread_mutexattr_getprotocol
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict protocol"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_getprotocol
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict protocol"
-.\" .Fc
+.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol"
.Ft int
-.Fo pthread_mutexattr_gettype
-.Fa "const pthread_mutexattr_t *restrict attr"
-.Fa "int *restrict type"
-.Fc
-.\" To match the SUS, this should be:
-.\" .Ft int
-.\" .Fo pthread_mutexattr_gettype
-.\" .Fa "pthread_mutexattr_t *restrict attr"
-.\" .Fa "int *restrict type"
-.\" .Fc
+.Fn pthread_mutexattr_getprotocol "pthread_mutexattr_t *attr" "int *protocol"
.Ft int
-.Fo pthread_mutexattr_init
-.Fa "pthread_mutexattr_t *attr"
-.Fc
+.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type"
.Ft int
-.Fo pthread_mutexattr_setprioceiling
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int prioceiling"
-.Fc
+.Fn pthread_mutexattr_gettype "pthread_mutexattr_t *attr" "int *type"
.Ft int
-.Fo pthread_mutexattr_setprotocol
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int protocol"
-.Fc
+.Fn pthread_mutexattr_setpolicy_np "pthread_mutexattr_t *attr" "int policy"
.Ft int
-.Fo pthread_mutexattr_settype
-.Fa "pthread_mutexattr_t *attr"
-.Fa "int type"
-.Fc
+.Fn pthread_mutexattr_getpolicy_np "pthread_mutexattr_t *attr" "int *policy"
.Sh DESCRIPTION
Mutex attributes are used to specify parameters to
.Fn pthread_mutex_init .
-One attribute object can be used in multiple calls to
-.Fn pthread_mutex_init ,
+Like with thread attributes,
+one attribute object can be used in multiple calls to
+.Xr pthread_mutex_init 3 ,
with or without modifications between calls.
.Pp
The
.Fn pthread_mutexattr_init
function initializes
.Fa attr
-with all of the default mutex attributes.
+with all the default mutex attributes.
.Pp
The
.Fn pthread_mutexattr_destroy
.Pp
The
.Fn pthread_mutexattr_settype
-function sets the mutex type value of the attribute. Valid mutex types are:
-.Dv PTHREAD_MUTEX_NORMAL ,
-.Dv PTHREAD_MUTEX_ERRORCHECK ,
-.Dv PTHREAD_MUTEX_RECURSIVE ,
-and
-.Dv PTHREAD_MUTEX_DEFAULT .
-The default mutex type for
-.Fn pthread_mutexattr_init
-is
-.Dv PTHREAD_MUTEX_DEFAULT .
-.Pp
-.Dv PTHREAD_MUTEX_NORMAL
-mutexes do not check for usage errors.
-.Dv PTHREAD_MUTEX_NORMAL
-mutexes will deadlock if reentered, and result in undefined behavior if a
-locked mutex is unlocked by another thread. Attempts to unlock an already
-unlocked
+functions set the mutex
+.Fa type
+value of the attribute.
+Valid mutex types are:
+.Bl -tag -width "XXX" -offset 2n
+.It Dv PTHREAD_MUTEX_NORMAL
+This type of mutex does not check for usage errors.
+It will deadlock if reentered, and result in undefined behavior if a
+locked mutex is unlocked by another thread.
+Attempts to unlock an already unlocked
.Dv PTHREAD_MUTEX_NORMAL
mutex will result in undefined behavior.
-.Pp
-.Dv PTHREAD_MUTEX_ERRORCHECK
-mutexes do check for usage errors.
+.It Dv PTHREAD_MUTEX_ERRORCHECK
+These mutexes do check for usage errors.
If an attempt is made to relock a
.Dv PTHREAD_MUTEX_ERRORCHECK
mutex without first dropping the lock, an error will be returned.
If a thread attempts to unlock a
.Dv PTHREAD_MUTEX_ERRORCHECK
-mutex that is locked by another thread, an error will be returned. If a
-thread attempts to unlock a
+mutex that is locked by another thread, an error will be returned.
+If a thread attempts to unlock a
.Dv PTHREAD_MUTEX_ERRORCHECK
thread that is unlocked, an error will be returned.
-.Pp
-.Dv PTHREAD_MUTEX_RECURSIVE
-mutexes allow recursive locking.
+.It Dv PTHREAD_MUTEX_RECURSIVE
+These mutexes allow recursive locking.
An attempt to relock a
.Dv PTHREAD_MUTEX_RECURSIVE
-mutex that is already locked by the same thread succeeds. An equivalent
-number of
+mutex that is already locked by the same thread succeeds.
+An equivalent number of
.Xr pthread_mutex_unlock 3
-calls are needed before the mutex will wake another thread waiting on this
-lock. If a thread attempts to unlock a
+calls are needed before the mutex will wake another thread waiting
+on this lock.
+If a thread attempts to unlock a
.Dv PTHREAD_MUTEX_RECURSIVE
-mutex that is locked by another thread, an error will be returned. If a thread attemps to unlock a
+mutex that is locked by another thread, an error will be returned.
+If a thread attempts to unlock a
.Dv PTHREAD_MUTEX_RECURSIVE
thread that is unlocked, an error will be returned.
.Pp
-.Dv PTHREAD_MUTEX_DEFAULT
-mutexes result in undefined behavior if reentered.
+It is advised that
+.Dv PTHREAD_MUTEX_RECURSIVE
+mutexes are not used with condition variables.
+This is because of the implicit unlocking done by
+.Xr pthread_cond_wait 3
+and
+.Xr pthread_cond_timedwait 3 .
+.It Dv PTHREAD_MUTEX_DEFAULT
+Also this type of mutex will cause undefined behavior if reentered.
Unlocking a
.Dv PTHREAD_MUTEX_DEFAULT
-mutex locked by another thread will result in undefined behavior. Attempts to unlock an already
-unlocked
+mutex locked by another thread will result in undefined behavior.
+Attempts to unlock an already unlocked
.Dv PTHREAD_MUTEX_DEFAULT
mutex will result in undefined behavior.
+This is the default mutex type for
+.Fn pthread_mutexaddr_init .
+.El
.Pp
.Fn pthread_mutexattr_gettype
functions copy the type value of the attribute to the location pointed to by the second parameter.
.Pp
The
+.Fn pthread_mutexattr_setpolicy_np
+function sets the mutex
+.Fa policy
+value of the attribute.
+Valid mutex policies are:
+.Bl -tag -width "XXX" -offset 2n
+.It Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
+The first-fit mutex policy allows acquisition of the mutex to occur in any
+order. This policy is similar in operation to os_unfair_lock, new contending
+acquirers may obtain ownership of the mutex ahead of existing waiters.
+.It Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP
+The fairshare mutex policy guarantees that ownership of a contended mutex will
+be granted to waiters on a strictly ordered first-in, first-out basis. That is,
+a mutex holder that unlocks the mutex and then attempts to relock will wait
+behind existing threads already waiting on the mutex before being granted
+ownership again.
+.El
+.Pp
+The
+.Fn pthread_mutexattr_getpolicy_np
+function copies the mutex
+.Fa policy
+value of the attribute to the location pointed to by the second parameter.
+.Pp
+The
.Fn pthread_mutexattr_set*
functions set the attribute that corresponds to each function name.
.Pp
.Sh RETURN VALUES
If successful, these functions return 0.
Otherwise, an error number is returned to indicate the error.
+.Sh ENVIRONMENT
+The following environment variables change the behavior of the pthread mutex
+implementation.
+.Bl -tag -width "XXX" -offset 2n
+.It Ev PTHREAD_MUTEX_DEFAULT_POLICY
+Controls the process-wide policy used when initializing a pthread_mutex_t that
+has not had a policy set via
+.Fn pthread_mutexattr_setpolicy_np .
+The valid values are mapped as:
+.Pp
+.Bl -tag -width "XXX"
+.It Fa 1
+.Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP
+.It Fa 3
+.Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
+.El
+.El
+.Sh BACKWARDS COMPATIBILITY
+Prior to macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) the only available
+pthread mutex policy mode was
+.Dv PTHREAD_MUTEX_POLICY_FAIRSHARE_NP .
+macOS 10.14 (iOS and tvOS 12.0, watchOS 5.0) introduces
+.Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
+and also makes this the default mode for mutexes initialized without a policy
+attribute set.
+.Pp
+Attempting to use
+.Fn pthread_mutexattr_setpolicy_np
+to set the policy of a pthread_mutex_t to
+.Dv PTHREAD_MUTEX_POLICY_FIRSTFIT_NP
+on earlier releases will fail with
+.Er EINVAL
+and the mutex will continue to operate in fairshare mode.
.Sh ERRORS
+The
.Fn pthread_mutexattr_init
-will fail if:
+function shall fail if:
.Bl -tag -width Er
.It Bq Er ENOMEM
Out of memory.
.El
.Pp
+The
.Fn pthread_mutexattr_destroy
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
+The
.Fn pthread_mutexattr_setprioceiling
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa prioceiling .
.El
.Pp
+The
.Fn pthread_mutexattr_getprioceiling
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
+The
.Fn pthread_mutexattr_setprotocol
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa protocol .
.El
.Pp
+The
.Fn pthread_mutexattr_getprotocol
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
.Pp
+The
.Fn pthread_mutexattr_settype
-will fail if:
+function shall fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
-Invalid value for
-.Fa attr ,
-or invalid value for
-.Fa type .
+The value specified either by
+.Fa type
+or
+.Fa attr
+is invalid.
.El
.Pp
+The
.Fn pthread_mutexattr_gettype
-will fail if:
+function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
Invalid value for
.Fa attr .
.El
+.Pp
+The
+.Fn pthread_mutexattr_setpolicy_np
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+Invalid value for
+.Fa attr .
+.El
+.Pp
+The
+.Fn pthread_mutexattr_getpolicy_np
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The value specified either by
+.Fa type
+or
+.Fa attr
+is invalid.
+.El
.Sh SEE ALSO
.Xr pthread_mutex_init 3
.Sh STANDARDS
+The
.Fn pthread_mutexattr_init
and
.Fn pthread_mutexattr_destroy
-conform to
+functions conform to
.St -p1003.1-96
.Pp
+The
.Fn pthread_mutexattr_setprioceiling ,
.Fn pthread_mutexattr_getprioceiling ,
.Fn pthread_mutexattr_setprotocol ,
.Fn pthread_mutexattr_settype ,
and
.Fn pthread_mutexattr_gettype
-conform to
+functions conform to
.St -susv2
projects / apple / libpthread.git / blobdiff