MPCreateTask

OSStatus MPCreateTask (
                     TaskProc entryPoint,
                     void *parameter,
                     ByteCount stackSize,
                     MPQueueID notifyQueue,
                     void *terminationParameter1,
                     void *terminationParameter2,
                     MPTaskOptions options,
                     MPTaskID *task);

entryPoint

A pointer of type TaskProc that references the task function. The task function should take a single 32-bit parameter and return a value of type OSStatus .

parameter

The parameter to pass to the task function.

stackSize

A value of type ByteCount that specifies the size of the stack assigned to the task. Note that you should be careful not to exceed the bounds of the stack, since stack overflows may not be detected. Specifying zero for the size will result in a default stack size of 4KB.

notifyQueue

A value of type MPQueueID that specifies the ID of the message queue to which the system will send a message when the task terminates. You specify the first 64-bits of the message in the parameters terminationParameter1 and terminationParameter2 respectively. The last 32-bits contain the result code of the task function.

terminationParameter1

A 32-bit value that is sent to the message queue specified by the parameter notifyQueue when the task terminates.

terminationParameter2

A 32-bit value that is sent to the message queue specified by the parameter notifyQueue when the task terminates.

options

A value of type MPTaskOptions that specifies optional attributes of the preemptive task. See Task Creation Options for a list of possible values.

task

A pointer to a variable of type MPTaskID . On return, the variable contains the ID of the newly created task.

function result

A result code. See Result Codes for a list of possible values. If MPCreateTask could not create the task because some critical resource was not available, the function returns kMPInsufficientResourcesErr . Usually this is due to lack of memory to allocate the internal data structures associated with the task or the stack. The function also returns kMPInsufficientResourcesErr if any reserved option bits are set.

DISCUSSION

Tasks are created in the unblocked state, ready for execution. A task can terminate in the following ways:

By returning from its entry point
By calling MPExit
When specified as the target of an MPTerminateTask call
If a hardware-detected exception or programming exception occurs and no exception handler is installed
If the application calls ExitToShell

Task resources (its stack, active timers, internal structures related to the task, and so on) are reclaimed by the system when the task terminates. The task's address space is inherited from the process address space. All existing tasks are terminated when the owning process terminates.

VERSION NOTES

Introduced with Multiprocessing Services 1.0.

MPCreateTask

DISCUSSION

VERSION NOTES

SEE ALSO