32.69. $createCoroutine

$createCoroutine is used to create a new coroutine. If successful, it allocates a PROCEDURE call stack and a $coroutine record and returns a POINTER to the record. The CLASS $coroutine is described in Chapter 21. The $coroutine POINTER can be used to resume or kill the coroutine or access the fields of the $coroutine record. $createCoroutine does not cause the coroutine to start executing; it just allocates and initializes the coroutine. A subsequent call to $resumeCoroutine is used to transfer control to it and have it start executing.

initDataSec points to the data section to be used when the coroutine is first resumed. This POINTER can be obtained from the MAINSAIL system PROCEDURE bind, new, or thisDataSection.

initProcName is the name of the PROCEDURE where execution is to start when the coroutine is first resumed. The PROCEDURE must be typeless and parameterless, and must be in a MODULE for which initDataSec is a data section. MAINSAIL does not check whether the named PROCEDURE is in fact typeless and parameterless; violation of this rule results in undefined behavior.

coroutineName is the name (which is converted to upper case) to be given to the coroutine. It can be any STRING, except that it must not be the same as the name for any existing coroutine. If the argument is omitted, the next name from the sequence coroutine1, coroutine2, coroutine3, etc., is used.

The name of the root coroutine is MAINSAIL.

stackPages is the number of pages to be allocated for the stack. If omitted, the default specified in the bootstrap is used. It is difficult to estimate how large the stack should be; if a coroutine involves a deeply nested set of PROCEDURE calls, or a deep level of recursion, then the default stack size may not be sufficient. If a stack does overflow, the program may fail in some undefined manner.

The only valid ctrlBits bit is errorOK, which indicates that if an error is detected (e.g., coroutineName is already assigned), then no error message is to be generated. In any case, an error causes NULLPOINTER to be returned.

parent specifies the parent coroutine of the new coroutine. If parent is Zero, the coroutine is created as a child of the current coroutine.

The parameter foreignStackPages specifies the number of pages (of $pageSize bytes) to allocate for the foreign stack of the coroutine being created. foreignStackPages is ignored on platforms that do not allocate a separate foreign stack (all platforms except those for which the CONF FOREIGNSTACKSIZE command is defined).

On platforms that do allocate a separate foreign stack for each coroutine, if foreignStackPages is unspecified or less than or equal to zero, then if the CONF FOREIGNSTACKSIZE parameter for the current bootstrap is greater than zero, a foreign stack of the specified size is allocated; otherwise, a foreign stack of the same size as the MAINSAIL stack for that coroutine is allocated.