1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3
4<head>
5<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
6<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows">
7<META http-equiv="Content-Style-Type" content="text/css">
8<title>OS_LockMutex[R|W]</title>
9<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
10</head>
11
12<body>
13
14<h1 align="left">OS_LockMutex[R|W] <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></h1>
15<h2>Syntax</h2>
16
17<dl>
18  <dd>
19<CODE>#include &lt;nitro/os.h&gt;</CODE><BR> <BR> <CODE>void OS_LockMutexR( OSMutex* mutex );</CODE><BR>
20  </dd>
21  <dd><CODE>void OS_LockMutexW( OSMutex* mutex );</CODE></dd>
22</dl>
23
24
25<h2>Arguments</h2>
26<TABLE border="1" width="100%">
27  <TBODY>
28    <TR>
29      <TD width="13%"><CODE>mutex</CODE></TD>
30      <TD width="87%">Pointer to the <CODE>OSMutex</CODE> structure</TD>
31    </TR>
32  </TBODY>
33</TABLE>
34
35<h2>Return Values</h2>
36<p>None.</p>
37
38<H2>Description</H2>
39<P>The calling thread attempts to lock the mutex specified by <CODE>mutex</CODE>.</P>
40<P><CODE>mutex</CODE> is a pointer to an <CODE>OSMutex</CODE> structure.</P>
41<P>The <CODE>OS_LockMutexR</CODE> function attempts to <CODE>read lock</CODE> the mutex. If <CODE>mutex</CODE> is not being used or if is already set to <CODE>read lock</CODE> by another thread, the function returns immediately. The number of attempts is recorded, and <CODE>mutex</CODE> is not released if it has not been unlocked that same number of times. If <CODE>mutex</CODE> is set to <CODE>write lock</CODE> or if it is locked by the <CODE>OS_LockMutex</CODE> function, the called thread is paused until <CODE>mutex</CODE> is released.</P>
42<P><CODE>OS_LockMutexW</CODE> attempts to <CODE>write lock</CODE> the mutex. If <CODE>mutex</CODE> is not being used or if it is already locked by the current thread, the function returns immediately. The number of attempts is recorded, and <CODE>mutex</CODE> is not released if it has not been unlocked that same number of times. If <CODE>mutex</CODE> is set to <CODE>read lock</CODE>, or if it is set to <CODE>write lock</CODE> but is locked by another thread, or if it is locked by the <CODE>OS_LockMutex</CODE> function, the called thread is paused until <CODE>mutex</CODE> is released.</P>
43<P>Note that <CODE>mutex</CODE> must be initialized by the <CODE>OS_InitMutex</CODE> function. (If the mutex was just used in another lock-unlock process, it can be used again without initialization.)</P>
44<BLOCKQUOTE style="background-color:#ffffcc;"><B>Example</B><BR> <BR> <CODE>OSMutex myMutex;<BR> <BR> // Init mutex<BR> OS_InitMutex(&amp;myMutex);<BR> <BR> // read lock<BR> OS_LockMutexR(&amp;myMutex);<BR> :<BR> OS_UnlockMutexR(&amp;myMutex);<BR> <BR> // write lock<BR> OS_LockMutexW(&amp;myMutex);  <FONT color="#ff0000"> myMutex can be used since it is finished being used in a read lock</FONT><BR> :<BR> OS_UnlockMutexW(&amp;myMutex);<BR> <BR></CODE></BLOCKQUOTE>
45<H3><BR>Corresponding Unlock Functions</H3>
46<P>If <CODE>mutex</CODE> has been locked by the <CODE>OS_LockMutexR</CODE> function, unlock it using the <CODE>OS_UnlockMutexR</CODE> or <CODE>OS_UnlockMutexRW</CODE> function. You cannot unlock it using the <CODE>OS_UnlockMutexW</CODE> function.</P>
47<P>If <CODE>mutex</CODE> has been locked by the <CODE>OS_LockMutexW</CODE> function, unlock it using the <CODE>OS_UnlockMutexW</CODE> or <CODE>OS_UnlockMutexRW</CODE> function. You cannot unlock it using the <CODE>OS_UnlockMutexR</CODE> function.</P>
48<H3><BR>Exiting the Thread</H3>
49<P>When the thread that is locking <CODE>mutex</CODE> is ended by the <A href="../thread/OS_ExitThread.html"><CODE>OS_ExitThread</CODE></A> function, that mutex is automatically unlocked.</P>
50<H3><BR>Changing between <CODE>read lock</CODE> and <CODE>write lock</CODE></H3>
51<P>The change from <CODE>read lock</CODE> to <CODE>write lock</CODE> is performed using the <CODE><A href="OS_LockMutexFromToRW.html">OS_LockMutexFromRToW</A></CODE> and <CODE><A href="OS_TryLockMutexFromToRW.html">OS_TryLockMutexFromRToW</A></CODE> functions. In addition, the change from <CODE>write lock</CODE> to <CODE>read lock</CODE> is performed using the <CODE><A href="OS_LockMutexFromToRW.html">OS_LockMutexFromWToR</A></CODE> and <CODE><A href="OS_TryLockMutexFromToRW.html">OS_TryLockMutexFromWToR</A></CODE> functions. With both sets of functions, the transition does not involve switching threads.</P>
52<H3>Example</H3>
53<P>Consider the following situation.</P>
54<BLOCKQUOTE><IMG src="image_lock.gif" width="442" height="303" border="0"></BLOCKQUOTE>
55<P><CODE>read</CODE> is a function that can be simultaneously called from multiple threads because it reads but does not write data. This and the <CODE>write</CODE> function must be mutually exclusive because this data must not be read while it is being written, nor written while it is being read. While the mutex is locked by <CODE>read</CODE>, the calling thread will be suspended when control reaches the locking function in <CODE>write</CODE>. When the mutex is locked by <CODE>write</CODE>, it will also be locked by read. When the mutex is locked by <CODE>read</CODE>, however, other threads can execute <CODE>read</CODE>.</P>
56<P>Because <CODE>write</CODE> is a function that writes data, it would be a problem if other threads could read and write data while <CODE>write</CODE> is executing. When the mutex is locked by the <CODE>write</CODE> lock function, that same mutex is read locked. In short, during a  <CODE>write</CODE> lock other threads cannot execute <CODE>read</CODE> or <CODE>write</CODE>.</P>
57<h2>See Also</h2>
58<p><CODE><A href="OS_InitMutex.html">OS_InitMutex</A><BR> <A href="OS_UnlockMutex.html">OS_UnlockMutex</A><BR> <A href="OS_TryLockMutex.html">OS_TryLockMutex</A><BR> <A href="../thread/OS_ExitThread.html">OS_ExitThread</A></CODE><BR> <CODE><A href="OS_UnlockMutexRW.html">OS_UnlockMutexR</A><BR> <A href="OS_UnlockMutexRW.html">OS_UnlockMutexW</A><BR> <A href="OS_UnlockMutexRW.html">OS_UnlockMutexRW</A><BR> <A href="OS_TryLockMutexRW.html">OS_TryLockMutexR</A><BR> <A href="OS_TryLockMutexRW.html">OS_TryLockMutexW</A><BR> <A href="OS_LockMutexFromToRW.html">OS_LockMutexFromRToW</A><BR> <A href="OS_LockMutexFromToRW.html">OS_LockMutexFromWToR</A><BR> <A href="OS_TryLockMutexFromToRW.html">OS_TryLockMutexFromRToW</A><BR> <A href="OS_TryLockMutexFromToRW.html">OS_TryLockMutexFromWToR</A><br></CODE></p>
59<H2>Revision History</H2>
60<P>2008/12/16 Initial version.</P>
61<hr><p>CONFIDENTIAL</p></body>
62</html>
63