1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>PTHREAD_MUTEXATTR(3) manual page</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
<META NAME="CREATED" CONTENT="20050504;23040500">
<META NAME="CHANGED" CONTENT="20050505;18370400">
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>pthread_mutexattr_init, pthread_mutexattr_destroy,
pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation
attributes
</P>
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include <pthread.h></B>
</P>
<P><B>int pthread_mutexattr_init(pthread_mutexattr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_destroy(pthread_mutexattr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_settype(pthread_mutexattr_t *</B><I>attr</I><B>,
int </B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_gettype(const pthread_mutexattr_t *</B><I>attr</I><B>,
int *</B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_setkind_np(pthread_mutexattr_t *</B><I>attr</I><B>,
int </B><I>type</I><B>);</B>
</P>
<P><B>int pthread_mutexattr_getkind_np(const pthread_mutexattr_t
*</B><I>attr</I><B>, int *</B><I>type</I><B>);</B>
</P>
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P>Mutex attributes can be specified at mutex creation time, by
passing a mutex attribute object as second argument to
<A HREF="pthread_mutex_init.html"><B>pthread_mutex_init</B>(3)</A> .
Passing <B>NULL</B> is equivalent to passing a mutex attribute object
with all attributes set to their default values.
</P>
<P><B>pthread_mutexattr_init</B> initializes the mutex attribute
object <I>attr</I> and fills it with default values for the
attributes.
</P>
<P><B>pthread_mutexattr_destroy</B> destroys a mutex attribute
object, which must not be reused until it is reinitialized.</P>
<P>The following mutex types are supported:</P>
<P STYLE="margin-left: 2cm"><B>PTHREAD_MUTEX_NORMAL</B> - for
‘‘fast’’ mutexes.</P>
<P STYLE="margin-left: 2cm"><B>PTHREAD_MUTEX_RECURSIVE</B> - for
‘‘recursive’’ mutexes.</P>
<P STYLE="margin-left: 2cm"><B>PTHREAD_MUTEX_ERRORCHECK</B> - for
‘‘error checking’’ mutexes.</P>
<P>The mutex type determines what happens if a thread attempts to
lock a mutex it already owns with <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
. If the mutex is of the “normal” or “fast” type,
<A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
simply suspends the calling thread forever. If the mutex is of the
‘‘error checking’’ type, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
returns immediately with the error code <B>EDEADLK</B>. If the mutex
is of the ‘‘recursive’’ type, the call to
<A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
returns immediately with a success return code. The number of times
the thread owning the mutex has locked it is recorded in the mutex.
The owning thread must call <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
the same number of times before the mutex returns to the unlocked
state.
</P>
<P>The default mutex type is <B>PTHREAD_MUTEX_NORMAL</B></P>
<P><B>Pthreads-w32</B> also recognises the following equivalent types
that are used by Linux:</P>
<P STYLE="margin-left: 2cm; font-weight: medium"><B>PTHREAD_MUTEX_FAST_NP</B>
– equivalent to <B>PTHREAD_MUTEX_NORMAL</B></P>
<P STYLE="margin-left: 2cm"><B>PTHREAD_MUTEX_RECURSIVE_NP</B></P>
<P STYLE="margin-left: 2cm"><B>PTHREAD_MUTEX_ERRORCHECK_NP</B></P>
<P><B>pthread_mutexattr_settype</B> sets the mutex type attribute in
<I>attr</I> to the value specified by <I>type</I>.
</P>
<P><B>pthread_mutexattr_gettype</B> retrieves the current value of
the mutex kind attribute in <I>attr</I> and stores it in the location
pointed to by <I>type</I>.
</P>
<P><B>Pthreads-w32</B> also recognises the following equivalent
functions that are used in Linux:</P>
<P><B>pthread_mutexattr_setkind_np</B> is an alias for
<B>pthread_mutexattr_settype</B>.
</P>
<P STYLE="font-weight: medium"><B>pthread_mutexattr_getkind_np</B> is
an alias for <B>pthread_mutexattr_gettype</B>.
</P>
<H2><A HREF="#toc3" NAME="sect3">Return Value</A></H2>
<P><B>pthread_mutexattr_init</B>, <B>pthread_mutexattr_destroy</B>
and <B>pthread_mutexattr_gettype</B> always return 0.
</P>
<P><B>pthread_mutexattr_settype</B> returns 0 on success and a
non-zero error code on error.
</P>
<H2><A HREF="#toc4" NAME="sect4">Errors</A></H2>
<P>On error, <B>pthread_mutexattr_settype</B> returns the following
error code:
</P>
<DL>
<DT><B>EINVAL</B>
</DT><DD STYLE="margin-bottom: 0.5cm">
<I>type</I> is none of:<BR><B>PTHREAD_MUTEX_NORMAL</B>,
<B>PTHREAD_MUTEX_FAST_NP</B>,<BR><B>PTHREAD_MUTEX_RECURSIVE</B>,
<B>PTHREAD_MUTEX_RECURSIVE_NP,<BR>PTHREAD_MUTEX_ERRORCHECK</B>,
<B>PTHREAD_MUTEX_ERRORCHECK_NP</B>
</DD></DL>
<H2>
<A HREF="#toc5" NAME="sect5">Author</A></H2>
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
</P>
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
<H2><A HREF="#toc6" NAME="sect6">See Also</A></H2>
<P><A HREF="pthread_mutex_init.html"><B>pthread_mutex_init</B>(3)</A>
, <A HREF="pthread_mutex_lock.html"><B>pthread_mutex_lock</B>(3)</A>
, <A HREF="pthread_mutex_unlock.html"><B>pthread_mutex_unlock</B>(3)</A>
.
</P>
<H2><A HREF="#toc7" NAME="sect7"><U><FONT COLOR="#000080">Notes</FONT></U></A></H2>
<P>For speed, <B>Pthreads-w32</B> never checks the thread ownership
of mutexes of type <B>PTHREAD_MUTEX_NORMAL</B> (or
<B>PTHREAD_MUTEX_FAST_NP</B>) when performing operations on the
mutex. It is therefore possible for one thread to lock such a mutex
and another to unlock it.</P>
<P><SPAN STYLE="font-weight: medium">When developing code, it is a
common precaution to substitute the error checking type, and drop in
the normal type for release if the extra performance is required.</SPAN></P>
<HR>
<P><A NAME="toc"></A><B>Table of Contents</B></P>
<UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Return
Value</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Errors</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Author</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">See
Also</A></P>
<LI><P><A HREF="#sect7" NAME="toc7">Notes</A></P>
</UL>
</BODY>
</HTML>
|
