MapleStartRootTask
Start processing in the Task Programming Model
Calling Sequence
Parameters
Description
MapleStartRootTask(kv, void *output, int (M_DECL *TaskFunction)( void *, int, void * ), void *self, void (M_DECL *MarkTaskFunction)( void * ), void **ReturnValue, M_INT options )
kv
-
kernel handle of type MKernelVector
output
a pointer to the output struct for the root task
TaskFunction
a pointer to the function to execute as the root task
self
the argument to pass into the root task
MarkTaskFunction
the function called when a garbage collection occurs
ReturnValue
an output argument to hold the value passed into the MapleTaskReturn function
options
options for how the task model executes code
MapleStartRootTask is the entry point into the Task Programming Model from external call. It creates the first task in the model and then runs tasks until there are no tasks left.
Before using the Task Programming Model in external call, one should first become familiar with the Task Programming Model 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 for the task. The parent parameter is the input data for the task's parent. If the task wants to pass 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 a child task is created, and allows child tasks to differentiate themselves when updating their parent's input data. If the task is the root task, then arg_number will be the predefined value MAPLE_ROOT_TASK.
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.
When a task wants to create new child tasks, it calls the MapleCreateContinuationTask and MapleStartChildTask functions.
The MarkTaskFunction function is called if a garbage collection occurs and the root 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.
If the MapleTaskReturn function is called from with the newly created invocation of the Task Programming Model, the value passed into MapleTaskReturn will be assigned to the ReturnValue output parameter. If NULL is given for the ReturnValue parameter, then the value passed into MapleTaskReturn will be discarded.
MapleStartRootTask accepts options via the options parameter. Either pass 0 or the predefined value, MAPLE_TASK_NO_CALLBACKS. If the MAPLE_TASK_NO_CALLBACKS option is given, then the Task Programming API will not perform the work necessary to allow callbacks into the Maple kernel from within a task. This will slightly reduce the overhead of executing within the Task Programming Model. This option is remembered for any tasks created as a result of this execution of MapleStartRootTask.
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/MapleStartChildTask
OpenMaple/C/MapleTaskReturn
Download Help Document
