OSSaveCoroutine DEPRECATED

Syntax

#include <cafe/os.h>

void* OSSaveCoroutine(OSCoroutine *coroutine);

Parameters

coroutine Pointer to OSCoroutine that receives this coroutine's state.

Return Values

0 When called to save the current coroutine's state.
retval retval when resumed by OSLoadCoroutine.
1 When resumed by OSSwitchCoroutine.

Description

NOTE:
Although the Wii U coroutine API is not considered fully deprecated, it should not be used in new applications; threads should be used instead.

OSSaveCoroutine saves the state of the currently executing coroutine into the coroutine OSCoroutine. The saved state represents a point inside of the OSSaveCoroutine function itself. A call to OSLoadCoroutine or OSSwitchCoroutine in another coroutine can then return to this point by specifying the saved OSCoroutine.

When OSSaveCoroutine returns immediately after saving the current coroutine's state, it returns (void *) 0. Normally, you should test for this return value, and immediately switch to another coroutine if you receive it. For more information, see the sample code in OSSwitchCoroutine.

OSSaveCoroutine can return again at a later time upon a call to OSLoadCoroutine or OSSwitchCoroutine that specifies the OSCoroutine that was saved by the original call to OSSaveCoroutine. When this happens, OSSaveCoroutine returns a nonzero value: the value of retval if resumed by OSLoadCoroutine, or (void *)1 if resumed by OSSwitchCoroutine. Normally, you should test for this return value, and resume your coroutine's operation.

Do Not Call From

Deprecated Do not call this function in new code.
Multiple threads This function is not thread-safe.
Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.
Multiple Cores Do not call this function from more than one Core.

See Also

Coroutine Overview
OSInitCoroutine
OSLoadCoroutine
OSSwitchCoroutine

Revision History

2013/08/02 Clarify coroutine usage.
2013/05/08 Automated cleanup pass.
2012/08/01 Cleanup Pass.
2011/03/15 Initial version.


CONFIDENTIAL