MapleStartChildTask
Start a child task
Calling Sequence
Parameters
Description
MapleStartChildTask(kv, int arg_number, int (M_DECL *TaskFunction)( void *, int , void * ), void *self, void (M_DECL *MarkTaskFunction)( void * ) )
kv
-
kernel handle of type MKernelVector
arg_number
a positive integer to pass into the child task when that task is executed
TaskFunction
a pointer to the function to execute as the continuation task
self
the argument to pass into the continuation task
MarkTaskFunction
the function called when a garbage collection occurs
MapleStartChildTask creates a child task for the currently executing task. This task may start executing as soon as MapleStartChildTask returns. This function should only be called after a continuation task has been created, by calling MapleCreateContinuationTask.
Before using the Task Programming Model in external call, one should first become familiar with the Task Programming in Maple. The external call interface is more complex, so understanding the underlying model first will make the external call interface easier to understand.
In external call a task is a function and a data element. The task function must match the following prototype
int (M_DECL *TaskFunction)( void *parent, int arg_number, void *self )
The self parameter is the input data matching the task. The parent parameter is the input data matching the task's parent. If the task wants to return a value to its parent then it is the task's responsibility to update its parent's input data. The arg_number parameter is specified when the child task is created, and allows child tasks to differentiate themselves when updating their parent's input data.
For example:
#include "maplec.h"
struct TaskStruct {
M_INT myData;
M_INT parentLeft;
M_INT parentRight;
};
int M_DECL TaskFunction( void *parent, int arg_number, void *self )
{
struct TaskStruct *myArgs;
M_INT ret;
myArgs = (struct TaskStruct*)self;
ret = DoWork( myArgs );
switch( arg_number )
case MAPLE_ROOT_TASK:
(int)parent = ret; / Root task /
break;
case 1:
((struct TaskStruct*)parent)->parentLeft = ret;
case 2:
((struct TaskStruct*)parent)->parentRight = ret;
}
return 1;
Thus when the parent task executes (after all its children have executed) its input data will have been updated by its children.
The task function returns an int, however currently this value is not used.
After creating the continuation task, child tasks can be started by calling MapleStartChildTask functions.
The MarkTaskFunction function is called if a garbage collection occurs and the continuation task is still valid. The argument passed into MarkTaskFunction is the value passed as self. This allows the programmer the ability to maintain Maple data structures in the task and mark then when garbage collection occurs. See the MapleGcMark help pages for more information on marking.
For a complete example, see the OpenMaple/C/TaskProgramming page.
See Also
CustomWrapper
define_external
OpenMaple
OpenMaple/C/API
OpenMaple/C/Examples
OpenMaple/C/MapleCreateContinuationTask
OpenMaple/C/MapleStartRootTask
OpenMaple/C/MapleTaskReturn
Download Help Document
