.TH osCreateThread 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osCreateThread, osDestroyThread, \- register, unregister a
schedulable object
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
void osCreateThread(OSThread \(**t, OSId id, void (\(**entry)(void \(**),
			void \(**arg, void \(**sp, OSPri pri);
.sp .8v
void osDestroyThread(OSThread \(**t));
.Op
\f1
.fi
.SH DESCRIPTION
Threads are the basic schedulable unit of the Nintendo64 operating system.
The
.I OSThread
data structure stores the context of the thread and acts as
a handle by which the thread may be referenced by thread manipulation routines.
.PP
The
.I osCreateThread
routine initializes the given thread
.I t
and 
puts the thread on an active queue so that it may become known
to the Nintendo64 debugger,
.IR gvd (1P).
Threads are initialized in the stopped state and is expected that the
thread will eventually be placed on the run queue with the
.IR osStartThread (3P)
routine.
The
.I id
parameter is assigned to the thread by the application and is used solely
by the debugger user interface to provide a more convenient handle to
the thread than the thread structure address.
The procedure specifies by
.I entry
is jumped to when the thread is started,
and this procedure is passed the single argument
.I arg.
Similarly, the stack is initialized to
.I sp.
Note that stacks grow backwards (towards smaller addresses) with the
MIPS compiler tools.
The memory region assigned to the stack must be of least size
.I OS_MIN_STACKSIZE
in bytes.
The maximum size of the stack must be the sum of the stack frame sizes
of its maximum procedure call depth plus 16. Stacks must also be 64-bit
aligned, so they should be declared as 'long long int', and type-casted
when passed to this function.
The
.IR stacktool (1P)
program will be very helpful in computing stack sizes.
The
.I pri
argument specifies a nondegradable priority value that must range from
.I OS_PRIORITY_IDLE
(0) to
.I OS_PRIORITY_APPMAX
(127). In addition to enable all interrupts, this routine also specifies
the floating point control/status register to (1) flush denormalized numbers
to zero and to (2) signal invalid operation exception to catch generation 
of Not a Numbers (NaNs). For more information, refer to the Floating-Point 
Operations and Exceptions sections in the R4300 User's Manual.
.PP
The
.I osDestroyThread
routine removes the given thread
.I t
from the active queue as well as any other
queue the thread may be on.
More specifically,
if the thread was on the run queue it is no longer runnable;
if the thread was blocked on a message queue it may no longer send nor
receive a message.
If the argument is NULL,
the dispatcher is called and the invoking (running) thread is not returned
to the run queue.
Unexpected results will occur if a destroyed thread is ever placed back
on the run queue.
.SH "SEE ALSO"
.IR osGetThreadId (3P),
.IR osGetThreadPri (3P),
.IR osStartThread (3P),
.IR osStopThread (3P),
.IR osYieldThread (3P)