39.2. $killCoroutine

$killCoroutine is used to kill (deallocate) a coroutine and, by default, all of its descendants (i.e., all the coroutines that make up the subtree rooted at the argument coroutine). In each coroutine to be killed, $abortProcedureExcpt is first raised to allow the coroutine to clean up after itself. Then each dying coroutine's stack is deallocated and its $coroutine record is taken off all lists and marked as killed. An attempt to resume a killed coroutine is an error. The $coroutine record is reclaimed by the garbage collector when it becomes inaccessible.

$descendantKilledExcpt is raised in the ancestors of a killed coroutine to inform the coroutines that their descendant has died. The exception must be propagated with $raise; it may not be handled with $raiseReturn or by falling out of a handler. $exceptionPointerArg points to the $coroutine record of the dead coroutine, in which $abortProcedureExcpt has already been raised, but of which the $coroutine record has not yet been unlinked from the coroutine tree.

The root coroutine to be killed can be specified either by name or by a POINTER to its $coroutine record.

It is an error to kill the invoking coroutine or any of its ancestors; $resumeCoroutine must be used to kill the invoking coroutine.

Valid ctrlBits bits are errorOK and $nonRecursive. errorOK suppresses any error messages. If an error occurs, FALSE is returned, otherwise TRUE. If $nonRecursive is specified, $killCoroutine does not kill the specified coroutine's children, but replaces the dying coroutine in the coroutine tree with its children (the left-to-right order of the children is preserved). For example, if the coroutine tree looks like (in part):

|
A - B - C - D - E
        |
        F - G - H

then:

$killCoroutine("C",$nonRecursive)

produces the tree:

|
A - B - F - G - H - D - E