46.29. $resumeCoroutine

$resumeCoroutine is used to switch context from the current coroutine to another coroutine, and resume execution of the other coroutine where it last left off (usually at a call to $resumeCoroutine). If the coroutine has not yet been resumed (i.e., it has been created, but not yet given control), it invokes the PROCEDURE (the initializing PROCEDURE) specified when the coroutine was created with $createCoroutine, using the data section given at the same time. The context of the current coroutine is stored in its $coroutine record, to be used when it is next resumed. Control returns from $resumeCoroutine when the resuming coroutine is itself next resumed. If the coroutine being resumed is the same as the resuming coroutine, then control returns immediately, with no overall effect.

The exception $coroutineExcpt is raised if a coroutine attempts to return from its initializing PROCEDURE. The initializing PROCEDURE must terminate by means of a call to $resumeCoroutine.

If p is Zero in the POINTER form of $resumeCoroutine, $thisCoroutine.$next is resumed (it is an error if $thisCoroutine.$next is Zero).

The STRING form of $resumeCoroutine is equivalent to $resumeCoroutine($findCoroutine(coroutineName),ctrlBits).

The only valid ctrlBits bits are delete, errorOK, and $nonRecursive.

delete indicates that the current coroutine (and its subtree) is to be killed before resuming the target coroutine; see Section 39.2. It is an error to kill the target coroutine in this way; i.e., this option cannot be specified if the target coroutine is in the subtree rooted at the current coroutine.

The errorOK bit in ctrlBits is used to suppress error messages. In any case, if an error occurs, $resumeCoroutine returns FALSE, without resuming the coroutine. A value of TRUE means that the target coroutine was successfully resumed, and that the original coroutine has now itself been resumed from the coroutine given by $thisCoroutine.$next.

$nonRecursive is applicable only if the delete bit is set. The children of the current coroutine replace it in the coroutine tree, as if the current coroutine were killed by $killCoroutine with $nonRecursive set; see Section 39.2.