OSSetIdleFunction

Syntax

#include <revolution/os.h>

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

Arguments

idleFunction	Pointer to the function to be executed. Specifies a `NULL` pointer to cancel currently idle functions.
*`param`*	Arguments to be passed to the function.
*`stack`*	Stack used for idle functioins.
*`stackSize`*	Stack size (in bytes).

Return Values

Pointer to OSThread to execute the specified idle function.

Description

Creates a background thread that will execute while the game main loop is idle. Specifically, the operating system executes idleFunction while the game's main loop waits for the VIWaitForRetrace function to return.

The OSGetIdleFunction function's return value 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.