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=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>OSCreateThread</TITLE> 9</HEAD> 10<BODY> 11<H1>OSCreateThread</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><CODE>#include <revolution/os.h></CODE></PRE> 16 <DD> 17<PRE>BOOL OSCreateThread( 18OSThread* thread , 19void* (*func)(void*), 20void* param, 21void* stackBase, 22u32 stackSize , 23OSPriority priority, 24u16 attribute);</PRE> 25</DL> 26<H2>Arguments</H2> 27<TABLE border="1" cellpadding="3" cellspacing="0.1"> 28 <TBODY> 29 <TR> 30<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>thread</CODE></EM></STRONG></CODE></B></I></TD> 31<TD width="520">Pointer to thread control block to initialize.</TD> 32 </TR> 33 <TR> 34<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>func</CODE></EM></STRONG></CODE></B></I></TD> 35<TD width="520">Pointer to function from which to start execution.</TD> 36 </TR> 37 <TR> 38<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>param</CODE></EM></STRONG></CODE></B></I></TD> 39<TD width="520">Arguments to pass to the start function.</TD> 40 </TR> 41 <TR> 42<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>stackBase</CODE></EM></STRONG></CODE></B></I></TD> 43<TD width="520">Address of initial stack pointer. Note that stacks grow downward so this address should be the highest address in the stack.</TD> 44 </TR> 45 <TR> 46<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>stackSize</CODE></EM></STRONG></CODE></B></I></TD> 47<TD width="520">Size of the stack in bytes. Used to check if the stack is in the correct state.</TD> 48 </TR> 49 <TR> 50<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>priority</CODE></EM></STRONG></CODE></B></I></TD> 51<TD width="520">Base scheduling priority of thread. 0 is the highest priority, 31 is the lowest.<br>The default thread calling the <code>main</code> function (created by the <a href="../Init/OSInit.html"><code>OSInit</code></a> function) has a priority of 16.</TD> 52 </TR> 53 <TR> 54<TD width="120" bgcolor="#ffffe8"><I><B><CODE><STRONG><EM><CODE>attribute</CODE></EM></STRONG></CODE></B></I></TD> 55<TD width="520">OR'ed value of attributes. Current valid values: 56 <TABLE border="1" width="500" cellspacing="0.1"> 57 <TBODY> 58 <TR> 59<TD align="left" width="150"><CODE><B>OS_THREAD_ATTR_DETACH</B></CODE></TD> 60<TD width="350">The new thread is deleted when execution completes.</TD> 61 </TR> 62 <TR> 63 <TD align="left" width="150"><CODE><B>0</B></CODE></TD> 64<TD width="350">The thread control block remains in use until another thread is joined to this thread using the <CODE>OSJoinThread</CODE> function.</TD> 65 </TR> 66 </TBODY> 67 </TABLE> 68 </TD> 69 </TR> 70 </TBODY> 71</TABLE> 72<H2>Return Values</H2> 73<P><CODE>TRUE</CODE> if the function succeeds. Otherwise, <CODE>FALSE</CODE> (for example, wrong <FONT face="Courier New"><EM><STRONG>priority</STRONG></EM></FONT> value).</P> 74<H2>Description</H2> 75<P>Creates a new thread. The created thread is initially paused and must be put into the executable state by calling the <CODE><A href="OSResumeThread.html">OSResumeThread</A></CODE> function.</P> 76<P>This function takes the base (upper address) and size of the stack so that a magic word can be written into the last word of the stack. The <A href="OSCheckActiveThreads.html"><CODE>OSCheckActiveThreads</CODE></A> function checks for stack overflows. If unusual behavior is found in the game program, check to see if the value of the position of the word specified in the thread structure's <STRONG><EM><CODE>stackEnd</CODE></EM></STRONG>.</P> 77<P><STRONG>Note:</STRONG> Select <CODE>OS_THREAD_ATTR_DETACH</CODE> as the value for <CODE><EM><STRONG>attribute</STRONG></EM></CODE> to conform to the NINTENDO 64 thread mechanism. This value is set to free the thread control block without failure when thread execution ends. If nothing has been selected as an attribute (if the value of <CODE><EM><STRONG>attribute</STRONG></EM></CODE> equals zero), the operating system continues to use the thread control block until other threads that are joined to this thread using the <CODE><A href="OSJoinThread.html">OSJoinThread</A></CODE> function execute at the end. Accordingly, joined threads receive the return value of the thread that has ended. This return value is also useful for debugging because the thread context can be analyzed in the debugger after the thread has stopped. The detached attribute can also be set for a thread using the <CODE><A href="OSDetachThread.html">OSDetachThread</A></CODE> function.</P> 78 79<H2>See Also</H2> 80<P><a href="../list.html#Thread" target="contents">Thread Synchronization</a>, <a href="../list.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</a>, <a href="OSCancelThread.html"><code>OSCancelThread</code></a>, <a href="OSDetachThread.html"><code>OSDetachThread</code></a>, <code><a href="OSExitThread.html">OSExitThread</a>, <a href="OSResumeThread.html">OSResumeThread</a>, <a href="OSJoinThread.html">OSJoinThread</a>, <a href="OSCheckActiveThreads.html">OSCheckActiveThreads</a></code></P> 81<H2>Revision History</H2> 82<P>03/01/2006 Initial version.</P> 83</BODY> 84</HTML>