OSCreateThread

C Specification

#include <revolution/os.h>

BOOL OSCreateThread(
OSThread*  thread ,
void*    (*func)(void*),
void*          param,
void*      stackBase,
u32        stackSize ,
OSPriority priority,
u16        attribute);

Arguments

thread Pointer to thread control block to initialize.

func Pointer to function from which to start execution.

param Arguments to pass to the start function.

stackBase Address of initial stack pointer. Note that stacks grow downward so this address should be the highest address in the stack.

stackSize Size of the stack in bytes. Used to check if the stack is in the correct state.

priority Base scheduling priority of thread. 0 is the highest priority, 31 is the lowest.
The default thread calling the main function (created by the OSInit function) has a priority of 16.

attribute

OR'ed value of attributes. Current valid values:

`OS_THREAD_ATTR_DETACH`	The new thread is deleted when execution completes.
`0`	The thread control block remains in use until another thread is joined to this thread using the `OSJoinThread` function.

Return Values

TRUE if the function succeeds. Otherwise, FALSE (for example, wrong priority value).

Description

Creates a new thread. The created thread is initially paused and must be put into the executable state by calling the OSResumeThread function.

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 OSCheckActiveThreads 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 stackEnd.

Note: Select OS_THREAD_ATTR_DETACH as the value for attribute 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 attribute equals zero), the operating system continues to use the thread control block until other threads that are joined to this thread using the OSJoinThread 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 OSDetachThread function.

Revision History