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 13<H2>Syntax</H2> 14<dl><dd><pre class="construction">#include <revolution/os.h> 15 16BOOL OSCreateThread( 17 OSThread* thread, 18 void* (*func)(void*), 19 void* param, 20 void* stackBase, 21 u32 stackSize, 22 OSPriority priority, 23 u16 attribute); 24</pre></dd></dl> 25 26<H2>Arguments</H2> 27<TABLE class="arguments" border="1" > 28 <TBODY> 29 <TR> 30<TH>thread</TH> 31<TD>Pointer to thread control block to initialize.</TD> 32 </TR> 33 <TR> 34<TH><STRONG><EM><CODE>func</CODE></EM></STRONG></TH> 35<TD>Pointer to function from which to start execution.</TD> 36 </TR> 37 <TR> 38<TH><STRONG><EM><CODE>param</CODE></EM></STRONG></TH> 39<TD>Arguments to pass to the start function.</TD> 40 </TR> 41 <TR> 42<TH><STRONG><EM><CODE>stackBase</CODE></EM></STRONG></TH> 43<TD>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<TH><STRONG><EM><CODE>stackSize</CODE></EM></STRONG></TH> 47<TD>Size of the stack in bytes. Used to check if the stack is in the correct state.</TD> 48 </TR> 49 <TR> 50<TH><STRONG><EM><CODE>priority</CODE></EM></STRONG></TH> 51<TD>Base scheduling priority of thread. 0 is the highest priority, 31 is the lowest. The default thread, which calls the <CODE>main</CODE> function (and is created with the <A href="../Init/OSInit.html"><CODE>OSInit</CODE></A> function), has a priority of 16.</TD> 52 </TR> 53 <TR> 54<TH><STRONG><EM><CODE>attribute</CODE></EM></STRONG></TH> 55<TD>OR'ed value of attributes. Current valid values: 56 <TABLE class="arguments" border="1" > 57 <TBODY> 58 <TR> 59<TH>OS_THREAD_ATTR_DETACH</TH> 60<TD>The new thread is invalidated when execution completes.</TD> 61 </TR> 62 <TR> 63 <TH>0</TH> 64<TD>The thread control block remains used until another thread is joined to this thread by the <CODE>OSJoinThread</CODE> function.</TD> 65 </TR> 66 </TBODY> 67 </TABLE> 68 </TD> 69 </TR> 70 </TBODY> 71</TABLE> 72 73<H2>Return Values</H2> 74<P><CODE>TRUE</CODE> if the function succeeds. Otherwise, <CODE>FALSE</CODE> (for example, an illegal <SPAN class="argument">priority</SPAN> value).</P> 75 76<H2>Description</H2> 77<P>Creates a new thread. At first the created thread is placed in paused mode and must therefore be put in executable mode by calling the <A href="OSResumeThread.html"><CODE>OSResumeThread</CODE></A> function.</P> 78<P>This function takes the base (highest 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 that the stack does not overflow. If the program is found to be behaving oddly, be sure to check that the value of the word specified by "stackEnd" in the thread structure matches <CODE>OS_THREAD_STACK_MAGIC</CODE>.</P> 79<P>In Revolution OS, the current thread's stack is used when interrupt handlers run. Therefore, you must configure the stack size with some extra space taken into account.</P> 80<P>Note: Be sure to select <CODE>OS_THREAD_ATTR_DETACH</CODE> as the value for <SPAN class="argument">attribute</SPAN> in order to match the thread mechanism used by the NINTENDO64 (N64). This is done so that the thread control block is actually freed quickly when thread execution ends. If nothing has been selected as an attribute (if the value of <SPAN class="argument">attribute</SPAN> is 0), the thread control block will remain used by the operating system until other threads joined to this one (by the <A href="OSJoinThread.html"><CODE>OSJoinThread</CODE></A> function) have finished executing. Accordingly, threads joined later take the return value of the thread that has terminated. This is also useful for debugging, as the context of the thread can be analyzed in the debugger after it has terminated. The "detached" attribute can also be set for a thread using the <A href="OSDetachThread.html"><CODE>OSDetachThread</CODE></A> function.</P> 81 82<H2>See Also</H2> 83<P class="reference"> 84<A href="../toc.html#Thread" target="contents">Thread Functions</A>, 85<A href="../toc.html#ThreadSynchronization" target="contents">Thread Synchronization Functions</A>, 86<A href="OSCancelThread.html">OSCancelThread</A>, 87<A href="OSDetachThread.html">OSDetachThread</A>, 88<A href="OSExitThread.html">OSExitThread</A>, 89<A href="OSResumeThread.html">OSResumeThread</A>, 90<A href="OSJoinThread.html">OSJoinThread</A>, 91<A href="OSCheckActiveThreads.html">OSCheckActiveThreads</A> 92</P> 93 94<H2>Revision History</H2> 95<P> 962007/09/26 Added a note on stack usage by interrupt handlers.<BR>2006/03/01 Initial version.<BR> 97</P> 98<hr><p>CONFIDENTIAL</p></body> 99</HTML>