Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Multiprocessing Services Reference

Framework
CoreServices/CoreServices.h
Companion guide
Declared in
Multiprocessing.h
MultiprocessingInfo.h

Overview

Multiprocessing Services is an API that lets you create preemptive tasks in your application that can run on one or more microprocessors. Unlike the cooperative threads created by the Thread Manager, Multiprocessing Services automatically divides processor time among the available tasks, so that no particular task can monopolize the system. This document is relevant to you if you want to add multitasking capability to your Mac OS applications.

In Mac OS X, Carbon supports Multiprocessing Services with the following restrictions:

Functions by Task

Determining Multiprocessing Services And Processor Availability

Creating and Handling Message Queues

Creating and Handling Semaphores

Creating and Scheduling Tasks

Handling Critical Regions

Handling Event Groups

Handling Kernel Notifications

Accessing Per-Task Storage Variables

Memory Allocation Functions

Remote Calling Functions

Timer Services Functions

Exception Handling Functions

Debugger Support Functions

Functions

MPAllocate

Allocates a nonrelocatable memory block. (Deprecated. Use MPAllocateAligned instead.)

LogicalAddress MPAllocate (
   ByteCount size
);

Parameters
size

The size, in bytes, of the memory block to allocate.

Return Value

A pointer to the allocated memory. If the function cannot allocate the requested memory or the requested alignment, the returned address is NULL.

Availability
Declared In
Multiprocessing.h

MPAllocateAligned

Allocates a nonrelocatable memory block.

LogicalAddress MPAllocateAligned (
   ByteCount size,
   UInt8 alignment,
   OptionBits options
);

Parameters
size

The size, in bytes, of the memory block to allocate.

alignment

The desired alignment of the allocated memory block. See “Memory Allocation Alignment Constants” for a list of possible values to pass. Note that there will be a minimum alignment regardless of the requested alignment. If the requested memory block is 4 bytes or smaller, the block will be at least 4-byte aligned. If the requested block is greater than 4 bytes, the block will be at least 8-byte aligned.

options

Any optional information to use with this call. See “Memory Allocation Option Constants” for a list of possible values to pass.

Return Value

A pointer to the allocated memory. If the function cannot allocate the requested memory or the requested alignment, the returned address is NULL.

Discussion

The memory referenced by the returned address is guaranteed to be accessible by the application's cooperative task and any preemptive tasks that it creates, but not by other applications or their preemptive tasks. Any existing non-global heap blocks are freed when the application terminates. As with all shared memory, you must explicitly synchronize access to allocated heap blocks using a notification mechanism.

You can replicate the effect of the older MPAllocate function by calling MPAllocateAligned with 32-byte alignment and no options.

Also see the function MPFree.

Special Considerations

Mac OS X does not support allocation of global (cross address space) or resident memory with this function. In addition, passing the kMPAllocateNoGrowthMask constant in the options parameter has no effect in Mac OS X, since memory allocation is done with sparse heaps.

Availability
Declared In
Multiprocessing.h

MPAllocateTaskStorageIndex

Returns an index number to access per-task storage. 

OSStatus MPAllocateTaskStorageIndex (
   TaskStorageIndex *taskIndex
);

Parameters
index

On return, index contains an index number you can use to store task data.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

A call to the function MPAllocateTaskStorageIndex returns an index number that is common across all tasks in the current process. You can use this index number in calls to MPSetTaskStorageValue and MPGetTaskStorageValue to set a different value for each task using the same index.

You can think of the task storage area as a two dimensional array cross-referenced by the task storage index number and the task ID. Note that since the amount of per-task storage is determined when the task is created, the number of possible index values associated with a task is limited.

Also see the function MPDeallocateTaskStorageIndex.

Availability
Declared In
Multiprocessing.h

MPArmTimer

Arms the timer to expire at a given time. 

OSStatus MPArmTimer (
   MPTimerID timerID,
   AbsoluteTime *expirationTime,
   OptionBits options
);

Parameters
timerID

The ID of the timer you want to arm.

expirationTime

A pointer to a value that specifies when you want the timer to expire. Note that if you arm the timer with a time that has already passed, the timer expires immediately.

options

Any optional actions. See “Timer Option Masks” for a list of possible values.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If the timer has already expired, the reset does not take place and the function returns kMPInsufficientResourcesErr.

Discussion

The expiration time is an absolute time, which you can generate by calling the Driver Services Library function UpTime. When the timer expires, a notification is sent to the notification mechanism specified in the last MPSetTimerNotify call. If the specified notification ID has become invalid, no action is taken when the timer expires. The timer itself is deleted when it expires unless you specified the kMPPreserveTimerID option in the options parameter.

Also see the function MPCancelTimer.

Availability
Declared In
Multiprocessing.h

MPBlockClear

Clears a block of memory. 

void MPBlockClear (
   LogicalAddress address,
   ByteCount size
);

Parameters
address

The starting address of the memory block you want to clear.

size

The number of bytes you want to clear.

Discussion

As with all shared memory, your application must synchronize access to the memory blocks to avoid data corruption. MPBlockClear ensures the clearing stays within the bounds of the area specified by size, but the calling task can be preempted during the copying process.

Note that you can call this function from an interrupt handler.

Availability
Declared In
Multiprocessing.h

MPBlockCopy

Copies a block of memory.

void MPBlockCopy (
   LogicalAddress source,
   LogicalAddress destination,
   ByteCount size
);

Parameters
source

The starting address of the memory block you want to copy.

destination

The location to which you want to copy the memory block.

size

The number of bytes to copy.

Discussion

This function simply calls through to the Driver Services Library function BlockMoveData. Note that you should not make any assumptions about the state of the destination memory while this function is executing. In the intermediate state, values may be present that are neither the original nor the final ones. For example, this function may use the 'dcbz' instruction. If the underlying memory is not cacheable, if the memory is write-through instead of copy-back, or if the cache block is flushed for some reason, the 'dcbz' instruction will write zeros to the destination. You can avoid the use of the 'dcbz' instruction by calling BlockMoveDataUncached, but even that function makes no other guarantees about the memory block's intermediate state.

As with all shared memory, your application must synchronize access to the memory blocks to avoid data corruption. MPBlockCopy ensures the copying stays within the bounds of the area specified by size, but the calling task can be preempted during the copying process.

Note that you can call this function from an interrupt handler.

Availability
Declared In
Multiprocessing.h

MPCancelTimer

Cancels an armed timer. 

OSStatus MPCancelTimer (
   MPTimerID timerID,
   AbsoluteTime *timeRemaining
);

Parameters
timerID

The ID of the armed timer you want to cancel.

timeRemaining

On return, the timeRemaining contains the time remaining before the timer would have expired.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If the timer has already expired, this function returns kMPInsufficientResourcesErr.

Discussion

Also see the function MPArmTimer.

Availability
Declared In
Multiprocessing.h

MPCauseNotification

Signals a kernel notification. 

OSStatus MPCauseNotification (
   MPNotificationID notificationID
);

Parameters
notificationID

The ID of the kernel notification you want to signal.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

You call this function to signal a kernel notification much as you would signal any simple notification (for example, MPNotifyQueue ).

Availability
Declared In
Multiprocessing.h

MPCreateCriticalRegion

Creates a critical region object.

OSStatus MPCreateCriticalRegion (
   MPCriticalRegionID *criticalRegion
);

Parameters
criticalRegion

On return, the criticalRegion contains the ID of the newly created critical region object.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Also see the function MPDeleteCriticalRegion.

Availability
Declared In
Multiprocessing.h

MPCreateEvent

Creates an event group.

OSStatus MPCreateEvent (
   MPEventID *event
);

Parameters
event

On return, event contains the ID of the newly created event group.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Event groups are created from dynamically allocated internal resources. Other tasks may be competing for these resources so it is possible that this function will not be able to create an event group.

Also see the function MPDeleteEvent.

Availability
Declared In
Multiprocessing.h

MPCreateNotification

Creates a kernel notification

OSStatus MPCreateNotification (
   MPNotificationID *notificationID
);

Parameters
notificationID

On return, notificationID points to the newly created kernel notification.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

After creating the kernel notification object, you can add simple notifications by calling the function MPModifyNotification.

Also see the function MPDeleteNotification.

Availability
Declared In
Multiprocessing.h

MPCreateQueue

Creates a message queue.

OSStatus MPCreateQueue (
   MPQueueID *queue
);

Parameters
queue

On return, the variable contains the ID of the newly created message queue.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If a queue could not be created, MPCreateQueue returns kMPInsufficientResourcesErr.

Discussion

This call creates a message queue, which can be used to notify (that is, send) and wait for (that is, receive) messages consisting of three pointer-sized values in a preemptively safe manner.

Message queues are created from dynamically allocated internal resources. Other tasks may be competing for these resources so it is possible this function may not be able to create a queue.

See also the functions MPDeleteQueue and MPSetQueueReserve.

Availability
Declared In
Multiprocessing.h

MPCreateSemaphore

Creates a semaphore.

OSStatus MPCreateSemaphore (
   MPSemaphoreCount maximumValue,
   MPSemaphoreCount initialValue,
   MPSemaphoreID *semaphore
);

Parameters
maximumValue

The maximum allowed value of the semaphore.

initialValue

The initial value of the semaphore.

semaphore

On return, semaphore contains the ID of the newly–created semaphore.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

If you want to create a binary semaphore, you can call the macro MPCreateBinarySemaphore (MPSemaphoreID *semaphore) instead, which simply calls MPCreateSemaphore with both maximumValue and initialValue set to 1.

Also see the function MPDeleteSemaphore.

Availability
Declared In
Multiprocessing.h

MPCreateTask

Creates a preemptive task.

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 pointer-sized 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 two values of the message in the parameters terminationParameter1 and terminationParameter2 respectively. The last message value contains the result code of the task function.

terminationParameter1

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

terminationParameter2

A pointer-sized 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:

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.

Availability
Declared In
Multiprocessing.h

MPCreateTimer

Creates a timer.

OSStatus MPCreateTimer (
   MPTimerID *timerID
);

Parameters
timerID

On return, the timerID contains the ID of the newly created timer.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

You can use a timer to notify an event, queue, or semaphore after a specified amount of time has elapsed.

Timer objects are created from dynamically-allocated internal resources. Other tasks may be competing for these resources so it is possible this function may not be able to create one.

To specify the notification mechanism to signal, use the function MPSetTimerNotify.

Also see the functions MPDeleteTimer and MPArmTimer.

Availability
Declared In
Multiprocessing.h

MPCurrentTaskID

Obtains the task ID of the currently-executing preemptive task

MPTaskID MPCurrentTaskID (
   void
);

Return Value

The task ID of the current preemptive task. See the description of the MPTaskID data type.

Discussion

Returns the ID of the current preemptive task. If called from a cooperative task, this function returns an ID which is different than the ID of any preemptive task. Nonpreemptive processes may or may not have different task IDs for each application; future implementations of this API may behave differently in this regard.

Note that you can call this function from an interrupt handler.

Availability
Declared In
Multiprocessing.h

MPDataToCode

Designates the specified block of memory as executable code.

void MPDataToCode (
   LogicalAddress address,
   ByteCount size
);

Parameters
address

The starting address of the memory block you want to designate as code.

size

The size of the memory block.

Discussion

Since processors need to differentiate between code and data in memory, you should call this function to tag any executable code that your tasks may generate.

Note that you can call this function from an interrupt handler.

Availability
Declared In
Multiprocessing.h

MPDeallocateTaskStorageIndex

Frees an index number used to access per-task storage 

OSStatus MPDeallocateTaskStorageIndex (
   TaskStorageIndex taskIndex
);

Parameters
index

The index number you want to deallocate.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Also see the function MPAllocateTaskStorageIndex.

Availability
Declared In
Multiprocessing.h

MPDelayUntil

Blocks the calling task until a specified time. 

OSStatus MPDelayUntil (
   AbsoluteTime *expirationTime
);

Parameters
expirationTime

The time to unblock the task.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

You cannot call this function from a cooperative task.

Availability
Declared In
Multiprocessing.h

MPDeleteCriticalRegion

Removes the specified critical region object. 

OSStatus MPDeleteCriticalRegion (
   MPCriticalRegionID criticalRegion
);

Parameters
criticalRegion

The critical region object you want to remove.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Calling this function unblocks all tasks waiting to enter the critical region and their respective MPEnterCriticalRegion calls will return with the result code kMPDeletedErr.

Also see the function MPCreateCriticalRegion.

Availability
Declared In
Multiprocessing.h

MPDeleteEvent

Removes an event group. 

OSStatus MPDeleteEvent (
   MPEventID event
);

Parameters
event

The ID of the event group you want to remove.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

After deletion, the event ID becomes invalid, and all internal resources associated with the event group are reclaimed. Calling this function unblocks all tasks waiting on the event group and their respective MPWaitForEvent calls will return with the result code kMPDeletedErr.

Also see the function MPCreateEvent.

Availability
Declared In
Multiprocessing.h

MPDeleteNotification

Removes a kernel notification. 

OSStatus MPDeleteNotification (
   MPNotificationID notificationID
);

Parameters
notificationID

The ID of the notification you want to remove.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Also see the function MPCreateNotification.

Availability
Declared In
Multiprocessing.h

MPDeleteQueue

Deletes a message queue.

OSStatus MPDeleteQueue (
   MPQueueID queue
);

Parameters
queue

The ID of the message queue you want to delete.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

After calling MPDeleteQueue, the specified queue ID becomes invalid, and all internal resources associated with the queue (including queued messages) are reclaimed. Any tasks waiting on the queue are unblocked and their respective MPWaitOnQueue calls will return with the result code kMPDeletedErr.

Also see the function MPCreateQueue.

Availability
Declared In
Multiprocessing.h

MPDeleteSemaphore

Removes a semaphore. 

OSStatus MPDeleteSemaphore (
   MPSemaphoreID semaphore
);

Parameters
semaphore

The ID of the semaphore you want to remove.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Calling this function unblocks all tasks waiting on the semaphore and the tasks’ respective MPWaitOnSemaphore calls will return with the result code kMPDeletedErr.

Also see the function MPCreateSemaphore.

Availability
Declared In
Multiprocessing.h

MPDeleteTimer

Removes a timer. 

OSStatus MPDeleteTimer (
   MPTimerID timerID
);

Parameters
timerID

The ID of the timer you want to remove.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

After deletion, the timer ID becomes invalid, and all internal resources associated with the timer are reclaimed.

Also see the function MPCreateTimer.

Availability
Declared In
Multiprocessing.h

MPDisposeTaskException

Removes a task exception.

OSStatus MPDisposeTaskException (
   MPTaskID task,
   OptionBits action
);

Parameters
task

The task whose exception you want to remove.

action

Any actions to perform on the task. For example, you can enable single-stepping when the task resumes, or you can pass the exception on to another handler. See “Task Exception Disposal Constants” for a listing of possible values.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If the specified action is invalid or unsupported, or if the specified task is not suspended, this function returns kMPInsufficientResourcesErr.

Discussion

This function removes the task exception and allows the task to resume operation. If desired, you can enable single-stepping or branch-stepping, or propagate the exception instead.

Availability
Declared In
Multiprocessing.h

MPEnterCriticalRegion

Attempts to enter a critical region. 

OSStatus MPEnterCriticalRegion (
   MPCriticalRegionID criticalRegion,
   Duration timeout
);

Parameters
criticalRegion

The ID of the critical region you want to enter.

timeout

The maximum time to wait for entry before timing out. See “Timer Duration Constants” for a list of constants you can use to specify the wait interval.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

If another task currently occupies the critical region, the current task is blocked until the critical region is released or until the designated timeout expires. Otherwise the task enters the critical region and MPEnterCriticalRegion increments the region’s use count.

Once a task enters a critical region it can make further calls to MPEnterCriticalRegion without blocking (its use count increments for each call). However, each call to MPEnterCriticalRegion must be balanced by a call to MPExitCriticalRegion ; otherwise the region is not released for use by other tasks.

Note that you can enter a critical region from a cooperative task. Each cooperative task is treated as unique and different from any preemptive task. If you call this function from a cooperative task, you should specify only kDurationImmediate for the timeout length; other waits will cause the task to block.

Availability
Declared In
Multiprocessing.h

MPExit

Allows a task to terminate itself

void MPExit (
   OSStatus status
);

Parameters
status

An application-defined value that indicates termination status. This value is sent to the termination message queue in place of the task’s result code.

Discussion

When called from within a preemptive task, the task terminates, and the value indicated by the parameter status is sent to the termination message queue you specified in MPCreateTask. Note that you cannot call MPExit from outside a preemptive task.

Availability
Declared In
Multiprocessing.h

MPExitCriticalRegion

Exits a critical region. 

OSStatus MPExitCriticalRegion (
   MPCriticalRegionID criticalRegion
);

Parameters
criticalRegion

The ID of the critical region you want to exit.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If the task does not own the critical region specified by criticalRegion, MPExitCriticalRegion returns kMPInsufficientResourcesErr.

Discussion

This function decrements the use count of the critical region object. When the use count reaches zero, ownership of the critical region object is released (which allows another task to use the critical region).

Also see the function MPEnterCriticalRegion.

Availability
Declared In
Multiprocessing.h

MPExtractTaskState

Extracts state information from a suspended task.

OSStatus MPExtractTaskState (
   MPTaskID task,
   MPTaskStateKind kind,
   void *info
);

Parameters
task

The task whose state information you want to obtain.

kind

The kind of state information you want to obtain. See “Task State Constants” for a listing of possible values.

info

A pointer to a data structure to hold the state information. On return, the data structure holds the desired state information. The format of the data structure varies depending on the state information you want to retrieve. See the header file MachineExceptions.h for the formats of the various state information structures.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If you attempt to extract state information for a running task, this function returns kMPInsufficientResourcesErr.

Discussion

You can use this function to obtain register contents or exception information about a particular task.

Also see the function MPSetTaskState.

Availability
Declared In
Multiprocessing.h

MPFree

Frees memory allocated by MPAllocateAligned. 

void MPFree (
   LogicalAddress object
);

Parameters
object

A pointer to the memory you want to release.

Discussion

Also see the function MPAllocateAligned.

Availability
Declared In
Multiprocessing.h

MPGetAllocatedBlockSize

Returns the size of a memory block.

ByteCount MPGetAllocatedBlockSize (
   LogicalAddress object
);

Parameters
object

The address of the memory block whose size you want to determine.

Return Value

The size of the allocated memory block, in bytes.

Availability
Declared In
Multiprocessing.h

MPGetNextCpuID

Obtains the next CPU ID in the list of physical processors of the specified memory coherence group. 

OSStatus MPGetNextCpuID (
   MPCoherenceID owningCoherenceID,
   MPCpuID *cpuID
);

Parameters
owningCoherenceID

The ID of the memory coherence group whose physical processor IDs you want to obtain. Pass kMPInvalidIDErr, as only one coherence group, internal RAM, is currently defined.

cpuID

On return, cpuID points to the ID of the next physical processor.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

By iterating on this function (after calling MPProcessors , for example), you can obtain the IDs of all the processors available on the host computer. Generally, you would only use this function in diagnostic programs.

Availability
Declared In
MultiprocessingInfo.h

MPGetNextTaskID

Obtains the next task ID in the list of available tasks.

OSStatus MPGetNextTaskID (
   MPProcessID owningProcessID,
   MPTaskID *taskID
);

Parameters
owningProcessID

The ID of the process (typically the application) that owns the tasks. This ID is the same as the process ID handled by the Code Fragment Manager.

taskID

On return, taskID points to ID of the next task in the list of tasks.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

By iterating on this function, you can obtain the IDs of all the tasks in a given process. These tasks may be running, ready, or blocked. Generally you would only use this function in diagnostic programs.

Availability
Declared In
MultiprocessingInfo.h

MPGetTaskStorageValue

Gets the storage value stored at a specified index number. 

TaskStorageValue MPGetTaskStorageValue (
   TaskStorageIndex taskIndex
);

Parameters
index

The index number of the storage value you want to obtain.

Return Value

The value stored at the specified index number. See the description of the TaskStorageValue data type.

Discussion

Calling this function from within a task effectively reads a value in a two-dimensional array cross-referenced by task storage index value and the task ID.

Note that since this function does not return any status information, it may not be immediately obvious whether the returned storage value is valid.

Also see the function MPSetTaskStorageValue.

Availability
Declared In
Multiprocessing.h

MPModifyNotification

Adds a simple notification to a kernel notification.

OSStatus MPModifyNotification (
   MPNotificationID notificationID,
   MPOpaqueID anID,
   void *notifyParam1,
   void *notifyParam2,
   void *notifyParam3
);

Parameters
notificationID

The ID of the kernel notification you want to add to..

anID

The ID of the simple notification (semaphore, message group, or event group) you want to add to the kernel notification.

notifyParam1

If anID specifies an event group, this parameter should contain the flags to set in the event group when MPCauseNotification is called. If anID specifies a message queue, this parameter should contain the first pointer-sized value of the message to be sent to the message queue when MPCauseNotification is called.

notifyParam2

If anID specifies a message queue, this parameter should contain the second pointer-sized value of the message to be sent to the message queue when MPCauseNotification is called. Pass NULL if you don’t need this parameter.

notifyParam3

If anID specifies a message queue, this parameter should contain the third pointer-sized value of the message sent to the message queue when MPCauseNotification is called. Pass NULL if you don’t need this parameter.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

You specify the parameters for the simple notifications just as if you were calling the MPSetTimerNotify function.

Availability
Declared In
Multiprocessing.h

MPModifyNotificationParameters

OSStatus MPModifyNotificationParameters (
   MPNotificationID notificationID,
   MPOpaqueIDClass kind,
   void *notifyParam1,
   void *notifyParam2,
   void *notifyParam3
);

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Availability
Declared In
Multiprocessing.h

MPNotifyQueue

Sends a message to the specified message queue.

OSStatus MPNotifyQueue (
   MPQueueID queue,
   void *param1,
   void *param2,
   void *param3
);

Parameters
queue

The queue ID of the message queue you want to notify.

param1

The first pointer-sized value of the message to send.

param2

The second pointer-sized value of the message to send.

param3

The third pointer-sized value of the message to send.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

This function sends a message to the specified queue, which consist of the three parameters, param1, param2, and param3. The system does not interpret the three values which comprise the text of the message. If tasks are waiting on the specified queue, the first waiting task is unblocked and the task’s MPWaitOnQueue function completes.

Depending on the queue mode, the system either allocates messages dynamically or assigns them to memory reserved for the queue. In either case, if no more memory is available for messages MPNotifyQueue returns kMPInsufficientResourcesErr.

You can call this function from an interrupt handler if messages are reserved on the queue. For more information about queueing modes and reserving messages, see MPSetQueueReserve.

Also see the function MPWaitOnQueue.

Availability
Declared In
Multiprocessing.h

MPProcessors

Returns the number of processors on the host computer. 

ItemCount MPProcessors (
   void
);

Return Value

The number of physical processors on the host computer.

Discussion

See also the function MPProcessorsScheduled.

Availability
Declared In
Multiprocessing.h

MPProcessorsScheduled

Returns the number of active processors available on the host computer. 

ItemCount MPProcessorsScheduled (
   void
);

Return Value

The number of active processors available on the host computer.

Discussion

The number of active processors is defined as the number of processors scheduled to run tasks. This number varies while the system is running. Advanced power management facilities may stop or start scheduling processors in the system to control power consumption or to maintain a proper operating temperature.

See also the function MPProcessors.

Availability
Declared In
Multiprocessing.h

MPRegisterDebugger

Registers a debugger. 

OSStatus MPRegisterDebugger (
   MPQueueID queue,
   MPDebuggerLevel level
);

Parameters
queue

The ID of the queue to which you want exception messages and other information to be sent.

level

The level of this debugger with respect to other debuggers. Exceptions and informational messages are sent first to the debugger with the highest level. If more than one debugger attempts to register at a particular level, only the first debugger is registered. Other attempts return an error.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

In Mac OS X, this function is available but is not implemented. Use system debugging services to write a debugger for Mac OS X.

Availability
Declared In
Multiprocessing.h

MPRemoteCall

Calls a non-reentrant function and blocks the current task. 

void * MPRemoteCall (
   MPRemoteProcedure remoteProc,
   void *parameter,
   MPRemoteContext context
);

Parameters
remoteProc

A pointer to the application-defined function you want to call. See MPRemoteProcedure for more information about the form of this function.

parameter

A pointer to a parameter to pass to the application-defined function. For example, this value could point to a data structure or a memory location.

context

This parameter is ignored; specify kMPOwningProcessRemoteContext.

Return Value

The value that your remote procedure callback returned.

Discussion

You use this function to execute code on your application’s main task. The remoteProc function is scheduled on the application’s main run loop and run in the default mode (kCFRunloopDefaultMode). If you call this function from your application’s main task, the remoteProc function is executed immediately in the current mode without blocking the task; otherwise, calling this function blocks the current task until the remote call completes.

Availability
Declared In
Multiprocessing.h

MPRemoteCallCFM

Calls a non-reentrant function and blocks the current task. 

void * MPRemoteCallCFM (
   MPRemoteProcedure remoteProc,
   void *parameter,
   MPRemoteContext context
);

Parameters
remoteProc

A pointer to the application-defined CFM (Code Fragment Manager) function you want to call. See MPRemoteProcedure for more information about the form of this function.

parameter

A pointer to a parameter to pass to the application-defined function. For example, this value could point to a data structure or a memory location.

context

This parameter is ignored; specify kMPOwningProcessRemoteContext.

Return Value

The value that your remote procedure callback returned.

Discussion

You use this function to execute code on your application’s main task. The remoteProc function is scheduled on the application’s main run loop and run in the default mode (kCFRunloopDefaultMode). If you call this function from your application’s main task, the remoteProc function is executed immediately in the current mode without blocking the task; otherwise, calling this function blocks the current task until the remote call completes.

Availability
Declared In
Multiprocessing.h

MPSetEvent

Merges event flags into a specified event group. 

OSStatus MPSetEvent (
   MPEventID event,
   MPEventFlags flags
);

Parameters
event

The ID of the event group you want to set.

flags

The flags you want to merge into the event group.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

The flags are logically ORed with the current flags in the event group. This procedure is an atomic operation to ensure that multiple updates do not get lost. If tasks are waiting on this event group, the first waiting task is unblocked.

Note that you can call this function from an interrupt handler.

Also see the function MPWaitForEvent.

Availability
Declared In
Multiprocessing.h

MPSetExceptionHandler

Sets an exception handler for a task. 

OSStatus MPSetExceptionHandler (
   MPTaskID task,
   MPQueueID exceptionQ
);

Parameters
task

The task to associate with the exception handler.

exceptionQ

The message queue to which an exception message will be sent.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

When an exception handler is set and an exception occurs, the task is suspended and a message is sent to the message queue specified by exceptionQ. The message contains the following information:

Availability
Declared In
Multiprocessing.h

MPSetQueueReserve

Reserves space for messages on a specified message queue. 

OSStatus MPSetQueueReserve (
   MPQueueID queue,
   ItemCount count
);

Parameters
queue

The ID of the queue whose messages you want to reserve.

count

The number of messages to reserve.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

MPNotifyQueue allocates spaces for messages dynamically; that is, memory to hold the message is allocated for the queue at the time of the call. In most cases this method is both speed and storage efficient. However, it is possible that, due to lack of memory resources, space for the message may not be available at the time of the call; in such cases, MPNotifyQueue will return kInsufficientResourcesErr.

If you must have guaranteed message delivery, or if you need to call MPNotifyQueue from an interrupt handler, you should reserve space on the specified queue by calling MPSetQueueReserve. Because such allocated space is reserved for duration of the queue’s existence, you should avoid straining internal system resources by reserving messages only when absolutely necessary. Note that if you have reserved messages on a queue, additional space cannot be added dynamically if the number of messages exceeds the number reserved for that queue.

The number of reserved messages is set to count, lowering or increasing the current number of reserved messages as required. If count is set to zero, no messages are reserved for the queue, and space for messages is allocated dynamically.

Availability
Declared In
Multiprocessing.h

MPSetTaskState

Sets state information for a suspended task. 

OSStatus MPSetTaskState (
   MPTaskID task,
   MPTaskStateKind kind,
   void *info
);

Parameters
task

The task whose state information you want to set.

kind

The kind of state information you want to set. See “Task State Constants” for a listing of possible values. Note that some state information is read-only and cannot be changed using this function.

info

A pointer to a data structure holding the state information you want to set. The format of the data structure varies depending on the state information you want to set. See the header file MachineExceptions.h for the formats of the various state information structures.

Return Value

A result code. See “Multiprocessing Services Result Codes.” If you specify kMPTaskState32BitMemoryException for the state information, this function returns kMPInsufficientResourcesErr, since the exception state information is read-only. Attempting to set state information for a running task will also return kMPInsufficientResourcesErr.

Discussion

You can use this function to set register contents or exception information for a particular task. However, some state information, such as the exception information (as specified by kMPTaskState32BitMemoryException) as well as the MSR, ExceptKind, DSISR, and DAR machine registers (specified under kMPTaskStateMachine) are read-only. Attempting to set the read-only machine registers will do nothing, while attempting to set the exception information will return an error.

Also see the function MPExtractTaskState.

Availability
Declared In
Multiprocessing.h

MPSetTaskStorageValue

Sets the storage value for a given index number. 

OSStatus MPSetTaskStorageValue (
   TaskStorageIndex taskIndex,
   TaskStorageValue value
);

Parameters
index

The index number whose storage value you want to set.

value

The value you want to set.

Return Value

A result code. See “Multiprocessing Services Result Codes.”

Discussion

Typically you use MPSetTaskStorageValue to store pointers to task-specific structures or data.

Calling this function from within a task effectively assigns a value in a two-dimensional array cross-referenced by task storage index value and the task ID.

Also see the function MPGetTaskStorageValue.

Availability
Declared In
Multiprocessing.h

MPSetTaskType

Sets the type of the task.

OSStatus MPSetTaskType (
   MPTaskID task,
   OSType taskType
);

Return Value

The noErr result code. See “Multiprocessing Services Result Codes.”

Discussion

This function does nothing and should not be used.

Availability
Declared In
Multiprocessing.h

MPSetTaskWeight

Assigns a relative weight to a task, indicating how much processor time it should receive compared to other available tasks. 

OSStatus MPSetTaskWeight (
   MPTaskID task,