macOS Multi-threaded programming

MPCreateTask
Creates a preemptive task.

Modified

OSStatus MPCreateTask (
TaskProc entryPoint,
void * parameter,
ByteCount stackSize,
MPQueueID notifyQueue,
void * terminationParameter1,
void * terminationParameter2,
MPTaskOptions options,
MPTaskID * task
);
Parameters
entryPoint
A pointer to 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
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.

Note that in Mac OS X prior to version 10.1, this parameter is ignored, and all stacks have the default size of 512 KB. Versions 10.1 and later do not have this limitation.

notifyQueue
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
Optional attributes of the preemptive task. See Task Creation Options for a list of possible values.

task
On return, task points to the ID of the newly created task.

Return Value
A result code. See "Multiprocessing Services Result Codes". 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.

To set the relative processor weight to be assigned to a task, use the function MPSetTaskWeight.

See also the function MPTerminateTask.

Version Notes
Introduced with Multiprocessing Services 1.0.

Availability
Modified in Carbon. Available in CarbonLib 1.0 and later when MultiprocessingLib 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Carbon Porting Notes
In Mac OS X prior to version 10.1, the stackSize parameter is ignored, and all stacks have the default size of 512 KB. Versions 10.1 and later do not have this limitation.

Declared In
Multiprocessing.h

Click to expand...