OSSetIdleFunction

C Specification

#include <revolution/os.h>

OSThread* OSSetIdleFunction( OSIdleFunction idleFunction,
                             void*          param,
                             void*          stack,
                             u32            stackSize );

Arguments

`idleFunction`	Pointer to the function to execute. Specify a `NULL` pointer to cancel the current idle function.
`param`	Arguments to pass to the function.
`stack`	Stack used for idle functions.
`stackSize`	Stack size in bytes.

Return Values

Pointer to OSThread used for executing the specified idle functions.

Description

Creates a background thread that will execute while the game main loop is idle. In other words, the operating system will execute idleFunction while the game main loop is waiting for the VIWaitForRetrace function to return.

The return value of the OSGetIdleFunction function can be used to determine if the idle function has completed. If the background thread that this function creates is still active, a call to this function fails and returns NULL.

This function is intended to provide convenience for creating background tasks without worrying about thread management. If more than one background task is required, use the OSCreateThread function instead.

The OS will write a magic word (OS_THREAD_STACK_MAGIC) into the last word of the stack. Stacks grow downward, so the magic word will be at the lowest address. The OSCheckActiveThreads function will check to ensure that the magic word remains intact when it is invoked.

Revision History

2006/03/01 Initial version.