1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4<META http-equiv="Content-Type" content="text/html; charset=utf-8">
5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows">
6<META http-equiv="Content-Style-Type" content="text/css">
7<TITLE>OS_SleepThreadDirect</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">OS_SleepThreadDirect <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1>
12<H2>Syntax</H2>
13<DL>
14  <DD>
15  <PRE><CODE>#include &lt;nitro/os.h&gt;</CODE></PRE>
16  <PRE><CODE>void OS_SleepThreadDirect( OSThread* thread, OSThreadQueue*  queue );</CODE></PRE>
17</DL>
18<H2>Arguments</H2>
19<TABLE border="1" width="100%">
20  <TBODY>
21    <TR>
22<TD width="13%"><EM><STRONG>thread</STRONG></EM></TD>
23<TD width="87%">Pointer to the thread to be stopped</TD>
24    </TR>
25    <TR>
26<TD width="13%"><EM><STRONG>queue</STRONG></EM></TD>
27<TD width="87%">Pointer to the thread queue that registers the specified thread.<BR>If <CODE>NULL</CODE>, it is not registered to the thread queue.</TD>
28    </TR>
29  </TBODY>
30</TABLE>
31<H2>Return Values</H2>
32<P>None.</P>
33<H2>Description</H2>
34<P>Pauses the specified thread and registers it with the thread queue designated by <CODE>queue</CODE>.</P>
35<P>When the <A href="OS_WakeupThread.html"><CODE>OS_WakeupThread</CODE></A> function is called with <CODE>queue</CODE> or the <A href="OS_WakeupThreadDirect.html"><CODE>OS_WakeupThreadDirect</CODE></A> function is called with <CODE>thread</CODE>, the thread will transition from the suspended state to the runnable state.</P>
36<P><FONT color="#ff0000">When <B><I>thread</I></B> is not in an executable state, this function does nothing and returns.</FONT>This is done to prevent the queue list from being destroyed because a paused thread registered in another thread queue is also registered in still another thread queue.</P>
37<p>This function changes the thread state directly from outside without using specific signals, so extreme caution is necessary to avoid unexpected deadlock when used with a wait matrix or tasks involving a mutex. This function was created for a specialized purpose, so <FONT color="#ff0000">it should not be used on threads that call functions whose implementation details are unclear</FONT>.<BR> <BR>
38</p>
39<blockquote><code>Example:<BR> <br> /* Low priority thread to be executed first */<BR> thread_1_proc()<br> {<br> critical_task();<br> }<br> <br> /* High priority threads are executed later. */<br> thread_2_proc()<br> {<br> OS_SleepThreadDirect(thread_1, NULL);<br> critical_task();<br> OS_WakeupThreadDirect(thread_1);<br> }<br> <br> /* Tasks executed in common */<br> critical_task()<br> {<br> <FONT color="#ff0000">　　If executed here, the process may result in a deadlock.</FONT><br> <FONT color="#ff0000">　　- Functions related to exclusive control (such as LockMutex)</FONT><br> <FONT color="#ff0000">　　- Functions (such as FS) for which thread execution dependencies may arise due to the queue, etc.</FONT><br> }<br> <BR></code></blockquote>
40<H2>See Also</H2>
41<P><A href="OS_InitThread.html"><CODE>OS_InitThread</CODE></A><BR> <A href="OS_CreateThread.html"><CODE>OS_CreateThread</CODE></A><BR> <A href="OS_WakeupThread.html"><CODE>OS_WakeupThread</CODE></A><BR> <A href="OS_WakeupThreadDirect.html"><CODE>OS_WakeupThreadDirect</CODE></A><BR> <A href="OS_SleepThread.html"><CODE>OS_SleepThread</CODE></A></P>
42<H2>Revision History</H2>
43<P>2009/11/19 Explained that nothing happens when the thread is not in an executable state.<BR>2007/12/03  Added notes.<BR>2006/08/29 Added notes regarding how to use the function.<BR>2006/08/16 Initial version.</P>
44<hr><p>CONFIDENTIAL</p></body></HTML>