summaryrefslogtreecommitdiff
path: root/manual/pthread_mutex_init.html
diff options
context:
space:
mode:
authorrpj <rpj>2005-05-06 07:27:10 +0000
committerrpj <rpj>2005-05-06 07:27:10 +0000
commit7523c7c4d75652f67cd31cb123e1268790394c8b (patch)
tree0920ebf089ccb971e0878542f85486171a541a8a /manual/pthread_mutex_init.html
parentcf42850c77554311e62d3780f6a36cbc38e5e002 (diff)
''
Diffstat (limited to 'manual/pthread_mutex_init.html')
-rw-r--r--manual/pthread_mutex_init.html277
1 files changed, 277 insertions, 0 deletions
diff --git a/manual/pthread_mutex_init.html b/manual/pthread_mutex_init.html
new file mode 100644
index 0000000..f9982cf
--- /dev/null
+++ b/manual/pthread_mutex_init.html
@@ -0,0 +1,277 @@
+<!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_MUTEX(3) manual page</TITLE>
+ <META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
+ <META NAME="CREATED" CONTENT="20050505;5000">
+ <META NAME="CHANGED" CONTENT="20050505;19000600">
+ <!-- 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_mutex_init, pthread_mutex_lock, pthread_mutex_trylock,
+pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_destroy
+- operations on mutexes
+</P>
+<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
+<P><B>#include &lt;pthread.h&gt;</B>
+</P>
+<P><B>#include &lt;time.h&gt;</B></P>
+<P><B>pthread_mutex_t </B><I>fastmutex</I> <B>=
+PTHREAD_MUTEX_INITIALIZER;</B>
+</P>
+<P><B>pthread_mutex_t </B><I>recmutex</I> <B>=
+PTHREAD_RECURSIVE_MUTEX_INITIALIZER;</B>
+</P>
+<P><B>pthread_mutex_t </B><I>errchkmutex</I> <B>=
+PTHREAD_ERRORCHECK_MUTEX_INITIALIZER;</B>
+</P>
+<P><B>pthread_mutex_t </B><I>recmutex</I> <B>=
+PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;</B>
+</P>
+<P><B>pthread_mutex_t </B><I>errchkmutex</I> <B>=
+PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;</B>
+</P>
+<P><B>int pthread_mutex_init(pthread_mutex_t *</B><I>mutex</I><B>,
+const pthread_mutexattr_t *</B><I>mutexattr</I><B>);</B>
+</P>
+<P><B>int pthread_mutex_lock(pthread_mutex_t *</B><I>mutex</I><B>);</B>
+</P>
+<P><B>int pthread_mutex_trylock(pthread_mutex_t *</B><I>mutex</I><B>);</B>
+</P>
+<P><B>int pthread_mutex_timedlock(pthread_mutex_t *</B><I>mutex,
+</I><B>const struct timespec *</B><I>abs_timeout</I><B>);</B>
+</P>
+<P><B>int pthread_mutex_unlock(pthread_mutex_t *</B><I>mutex</I><B>);</B>
+</P>
+<P><B>int pthread_mutex_destroy(pthread_mutex_t *</B><I>mutex</I><B>);</B>
+</P>
+<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
+<P>A mutex is a MUTual EXclusion device, and is useful for protecting
+shared data structures from concurrent modifications, and
+implementing critical sections and monitors.
+</P>
+<P>A mutex has two possible states: unlocked (not owned by any
+thread), and locked (owned by one thread). A mutex can never be owned
+by two different threads simultaneously. A thread attempting to lock
+a mutex that is already locked by another thread is suspended until
+the owning thread unlocks the mutex first.
+</P>
+<P><B>pthread_mutex_init</B> initializes the mutex object pointed to
+by <I>mutex</I> according to the mutex attributes specified in
+<I>mutexattr</I>. If <I>mutexattr</I> is <B>NULL</B>, default
+attributes are used instead.
+</P>
+<P>The type of a mutex determines whether it can be locked again by a
+thread that already owns it. The default type is “normal”. See
+<A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_init</B>(3)</A>
+for more information on mutex attributes.
+</P>
+<P>Variables of type <B>pthread_mutex_t</B> can also be initialized
+statically, using the constants <B>PTHREAD_MUTEX_INITIALIZER</B> (for
+normal “fast” mutexes), <B>PTHREAD_RECURSIVE_MUTEX_INITIALIZER</B>
+(for recursive mutexes), and <B>PTHREAD_ERRORCHECK_MUTEX_INITIALIZER</B>
+(for error checking mutexes). <SPAN STYLE="font-weight: medium"> In
+the <B>Pthreads-w32</B> implementation, an application should still
+call <B>pthread_mutex_destroy</B> at some point to ensure that any
+resources consumed by the mutex are released.</SPAN></P>
+<P><B>pthread_mutex_lock</B> locks the given mutex. If the mutex is
+currently unlocked, it becomes locked and owned by the calling
+thread, and <B>pthread_mutex_lock</B> returns immediately. If the
+mutex is already locked by another thread, <B>pthread_mutex_lock</B>
+suspends the calling thread until the mutex is unlocked.
+</P>
+<P>If the mutex is already locked by the calling thread, the behavior
+of <B>pthread_mutex_lock</B> depends on the type of the mutex. If the
+mutex is of the “normal” type, the calling thread is suspended
+until the mutex is unlocked, thus effectively causing the calling
+thread to deadlock. If the mutex is of the ‘‘error checking’’
+type, <B>pthread_mutex_lock</B> returns immediately with the error
+code <B>EDEADLK</B>. If the mutex is of the ‘‘recursive’’
+type, <B>pthread_mutex_lock</B> succeeds and returns immediately,
+recording the number of times the calling thread has locked the
+mutex. An equal number of <B>pthread_mutex_unlock</B> operations must
+be performed before the mutex returns to the unlocked state.
+</P>
+<P><B>pthread_mutex_trylock</B> behaves identically to
+<B>pthread_mutex_lock</B>, except that it does not block the calling
+thread if the mutex is already locked by another thread (or by the
+calling thread in the case of a “normal” mutex). Instead,
+<B>pthread_mutex_trylock</B> returns immediately with the error code
+<B>EBUSY</B>.
+</P>
+<P><B>pthread_mutex_timedlock</B> behaves identically to
+<B>pthread_mutex_lock</B>, except that if it cannot acquire the lock
+before the <I>abs_timeout</I> time, the call returns with the error
+code <B>ETIMEDOUT</B>. If the mutex can be locked immediately it is,
+and the <B>abs_timeout</B> parameter is ignored.</P>
+<P><B>pthread_mutex_unlock</B> unlocks the given mutex. The mutex is
+assumed to be locked and owned by the calling thread on entrance to
+<B>pthread_mutex_unlock</B>. If the mutex is of the “normal”
+type, <B>pthread_mutex_unlock</B> always returns it to the unlocked
+state. If it is of the ‘‘recursive’’ type, it decrements the
+locking count of the mutex (number of <B>pthread_mutex_lock</B>
+operations performed on it by the calling thread), and only when this
+count reaches zero is the mutex actually unlocked.
+</P>
+<P>On ‘‘error checking’’ mutexes, <B>pthread_mutex_unlock</B>
+actually checks at run-time that the mutex is locked on entrance, and
+that it was locked by the same thread that is now calling
+<B>pthread_mutex_unlock</B>. If these conditions are not met, an
+error code is returned and the mutex remains unchanged. ‘‘Normal’’
+mutexes perform no such checks, thus allowing a locked mutex to be
+unlocked by a thread other than its owner. This is non-portable
+behavior and is not meant to be used as a feature.</P>
+<P><B>pthread_mutex_destroy</B> destroys a mutex object, freeing the
+resources it might hold. The mutex must be unlocked on entrance.</P>
+<H2><A HREF="#toc3" NAME="sect3">Cancellation</A></H2>
+<P>None of the mutex functions is a cancellation point, not even
+<B>pthread_mutex_lock</B>, in spite of the fact that it can suspend a
+thread for arbitrary durations. This way, the status of mutexes at
+cancellation points is predictable, allowing cancellation handlers to
+unlock precisely those mutexes that need to be unlocked before the
+thread stops executing. Consequently, threads using deferred
+cancellation should never hold a mutex for extended periods of time.
+</P>
+<H2><A HREF="#toc4" NAME="sect4">Async-signal Safety</A></H2>
+<P>The mutex functions are not async-signal safe. What this means is
+that they should not be called from a signal handler. In particular,
+calling <B>pthread_mutex_lock</B> or <B>pthread_mutex_unlock</B> from
+a signal handler may deadlock the calling thread.
+</P>
+<H2><A HREF="#toc5" NAME="sect5">Return Value</A></H2>
+<P><B>pthread_mutex_init</B> always returns 0. The other mutex
+functions return 0 on success and a non-zero error code on error.
+</P>
+<H2><A HREF="#toc6" NAME="sect6">Errors</A></H2>
+<P>The <B>pthread_mutex_lock</B> function returns the following error
+code on error:
+</P>
+<DL>
+ <DL>
+ <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex has not been properly initialized.
+ </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ <B>EDEADLK</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex is already locked by the calling thread (‘‘error
+ checking’’ mutexes only).
+ </DD></DL>
+</DL>
+<P>
+The <B>pthread_mutex_trylock</B> function returns the following error
+codes on error:
+</P>
+<DL>
+ <DL>
+ <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex could not be acquired because it was currently locked.
+ </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ <B>EINVAL</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex has not been properly initialized.
+ </DD></DL>
+</DL>
+<P>
+The <B>pthread_mutex_timedlock</B> function returns the following
+error codes on error:
+</P>
+<DL>
+ <DL>
+ <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>ETIMEDOUT</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex could not be acquired before the <I>abs_timeout</I> time
+ arrived.
+ </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ <B>EINVAL</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex has not been properly initialized.
+ </DD></DL>
+</DL>
+<P>
+The <B>pthread_mutex_unlock</B> function returns the following error
+code on error:
+</P>
+<DL>
+ <DL>
+ <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex has not been properly initialized.
+ </DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ <B>EPERM</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the calling thread does not own the mutex (‘‘error checking’’
+ mutexes only).
+ </DD></DL>
+</DL>
+<P>
+The <B>pthread_mutex_destroy</B> function returns the following error
+code on error:
+</P>
+<DL>
+ <DL>
+ <DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EBUSY</B>
+ </DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
+ the mutex is currently locked.
+ </DD></DL>
+</DL>
+<H2>
+<A HREF="#toc7" NAME="sect7">Author</A></H2>
+<P>Xavier Leroy &lt;Xavier.Leroy@inria.fr&gt;
+</P>
+<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
+<H2><A HREF="#toc8" NAME="sect8">See Also</A></H2>
+<P><A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_init</B>(3)</A>
+, <A HREF="pthread_mutexattr_init.html"><B>pthread_mutexattr_settype</B>(3)</A>
+, <A HREF="pthread_cancel.html"><B>pthread_cancel</B>(3)</A> .
+</P>
+<H2><A HREF="#toc9" NAME="sect9">Example</A></H2>
+<P>A shared global variable <I>x</I> can be protected by a mutex as
+follows:
+</P>
+<PRE STYLE="margin-left: 1cm; margin-right: 1cm">int x;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;</PRE><BLOCKQUOTE STYLE="margin-left: 0cm; margin-right: 0cm">
+All accesses and modifications to <I>x</I> should be bracketed by
+calls to <B>pthread_mutex_lock</B> and <B>pthread_mutex_unlock</B> as
+follows:
+</BLOCKQUOTE>
+<PRE STYLE="margin-left: 1.03cm; margin-right: 2cm">pthread_mutex_lock(&amp;mut);
+/* operate on x */
+pthread_mutex_unlock(&amp;mut);</PRE>
+<HR>
+<BLOCKQUOTE STYLE="margin-right: 4cm"><A NAME="toc"></A><B>Table of
+Contents</B></BLOCKQUOTE>
+<UL>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">Cancellation</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">Async-signal
+ Safety</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">Return
+ Value</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">Errors</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">Author</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm; margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">See
+ Also</A>
+ </BLOCKQUOTE>
+ <LI><BLOCKQUOTE STYLE="margin-right: 4cm"><A HREF="#sect9" NAME="toc9">Example</A>
+ </BLOCKQUOTE>
+</UL>
+</BODY>
+</HTML>