Multiprocessing Services Reference

Framework
CoreServices/CoreServices.h
Companion guide
Multiprocessing Services Programming 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 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

_MPIsFullyInitialized

Indicates whether Multiprocessing Services is available for use.

Boolean _MPIsFullyInitialized (
   void
);
Return Value

If true, Multiprocessing Services is available for use; otherwise, false.

Declared In
Multiprocessing.h

Callbacks

MPRemoteProcedure

Defines a remote procedure call.

typedef void* (*MPRemoteProcedure) (
   void *parameter
);

For example, this is how you would declare the application-defined function if you were to name the function MyRemoteProcedure:

void* MyRemoteProcedure (
   void *parameter
);

Parameters
parameter

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

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

TaskProc

Defines the entry point of a task.

typedef OSStatus (*TaskProc) (
   void *parameter
);

For example, this is how you would declare the application-defined function if you were to name the function MyTaskProc:

OSStatus MyTaskProc (
   void *parameter
);

Parameters
parameter

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

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

Data Types

MPAddressSpaceID

typedef struct OpaqueMPAddressSpaceID * MPAddressSpaceID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPAddressSpaceInfo

struct MPAddressSpaceInfo {
   PBVersion version;
   MPProcessID processID;
   MPCoherenceID groupID;
   ItemCount nTasks;
   UInt32 vsid[16];
};
typedef struct MPAddressSpaceInfo MPAddressSpaceInfo;
Availability
  • Available in OS X v10.1 and later.
Declared In
MultiprocessingInfo.h

MPAreaID

typedef struct OpaqueMPAreaID * MPAreaID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPCoherenceID

Represents a memory coherence group.

typedef struct OpaqueMPCoherenceID * MPCoherenceID;
Discussion

A coherence group is the set of processors and other bus controllers that have cache-coherent access to memory. Mac OS 9 defines only one coherence group, which is all the processors that can access internal memory (RAM). Other coherence groups are possible; for example, a PCI card with its own memory and processors can comprise a coherence group.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPConsoleID

typedef struct OpaqueMPConsoleID * MPConsoleID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPCpuID

Represents a CPU ID.

typedef struct OpaqueMPCpuID * MPCpuID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPCriticalRegionID

Represents a critical region ID, which Multiprocessing Services uses to manipulate critical regions.

typedef struct OpaqueMPCriticalRegionID * MPCriticalRegionID;
Discussion

You obtain a critical region ID by calling the function MPCreateCriticalRegion.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPCriticalRegionInfo

struct MPCriticalRegionInfo {
   PBVersion version;
   MPProcessID processID;
   OSType regionName;
   ItemCount nWaiting;
   MPTaskID waitingTaskID;
   MPTaskID owningTask;
   ItemCount count;
};
typedef struct MPCriticalRegionInfo MPCriticalRegionInfo;
Availability
  • Available in OS X v10.0 and later.
Declared In
MultiprocessingInfo.h

MPEventFlags

Represents event information for an event group.

typedef UInt32 MPEventFlags;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPEventID

Represents an event group ID, which Multiprocessing Services uses to manipulate event groups.

typedef struct OpaqueMPEventID * MPEventID;
Discussion

You obtain an event group ID by calling the function MPCreateEvent.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPEventInfo

struct MPEventInfo {
   PBVersion version;
   MPProcessID processID;
   OSType eventName;
   ItemCount nWaiting;
   MPTaskID waitingTaskID;
   MPEventFlags events;
};
typedef struct MPEventInfo MPEventInfo;
Availability
  • Available in OS X v10.0 and later.
Declared In
MultiprocessingInfo.h

MPExceptionKind

Represents the kind of exception thrown.

typedef UInt32 MPExceptionKind;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPNotificationID

Represents a notification ID, which Multiprocessing Services uses to manipulate kernel notifications.

typedef struct OpaqueMPNotificationID * MPNotificationID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPNotificationInfo

struct MPNotificationInfo {
   PBVersion version;
   MPProcessID processID;
   OSType notificationName;
   MPQueueID queueID;
   void * p1;
   void * p2;
   void * p3;
   MPEventID eventID;
   MPEventFlags events;
   MPSemaphoreID semaphoreID;
};
typedef struct MPNotificationInfo MPNotificationInfo;
Availability
  • Available in OS X v10.0 and later.
Declared In
MultiprocessingInfo.h

MPOpaqueID

Represents a generic notification ID (that is, an ID that could be a queue ID, event ID, kernel notification ID, or semaphore ID).

typedef struct OpaqueMPOpaqueID * MPOpaqueID;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPOpaqueIDClass

typedef UInt32 MPOpaqueIDClass;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPPageSizeClass

typedef UInt32 MPPageSizeClass;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPProcessID

Represents a process ID.

typedef struct OpaqueMPProcessID * MPProcessID;
Discussion

Note that this process ID is identical to the process ID (or context ID) handled by the Code Fragment Manager.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPQueueID

Represents a queue ID, which Multiprocessing Services uses to manipulate message queues.

typedef struct OpaqueMPQueueID * MPQueueID;
Discussion

You obtain a queue ID by calling the function MPCreateQueue.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPQueueInfo

struct MPQueueInfo {
   PBVersion version;
   MPProcessID processID;
   OSType queueName;
   ItemCount nWaiting;
   MPTaskID waitingTaskID;
   ItemCount nMessages;
   ItemCount nReserved;
   void * p1;
   void * p2;
   void * p3;
};
typedef struct MPQueueInfo MPQueueInfo;
Availability
  • Available in OS X v10.0 and later.
Declared In
MultiprocessingInfo.h

MPSemaphoreCount

Represents a semaphore count.

typedef ItemCount MPSemaphoreCount;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPSemaphoreID

Represents a semaphore ID, which Multiprocessing Services uses to manipulate semaphores.

typedef struct OpaqueMPSemaphoreID * MPSemaphoreID;
Discussion

You obtain a semaphore ID by calling the function MPCreateSemaphore.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPSemaphoreInfo

struct MPSemaphoreInfo {
   PBVersion version;
   MPProcessID processID;
   OSType semaphoreName;
   ItemCount nWaiting;
   MPTaskID waitingTaskID;
   ItemCount maximum;
   ItemCount count;
};
typedef struct MPSemaphoreInfo MPSemaphoreInfo;
Availability
  • Available in OS X v10.0 and later.
Declared In
MultiprocessingInfo.h

MPTaskID

Represents a task ID.

typedef struct OpaqueMPTaskID * MPTaskID;
Discussion

You obtain a task ID by calling the function MPCreateTask.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPTaskInfo

Contains information about a task.

struct MPTaskInfo {
   PBVersion version;
   OSType name;
   OSType queueName;
   UInt16 runState;
   UInt16 lastCPU;
   UInt32 weight;
   MPProcessID processID;
   AbsoluteTime cpuTime;
   AbsoluteTime schedTime;
   AbsoluteTime creationTime;
   ItemCount codePageFaults;
   ItemCount dataPageFaults;
   ItemCount preemptions;
   MPCpuID cpuID;
   MPOpaqueID blockedObject;
   MPAddressSpaceID spaceID;
   LogicalAddress stackBase;
   LogicalAddress stackLimit;
   LogicalAddress stackCurr;
};
typedef struct MPTaskInfo MPTaskInfo;
Fields
version

The version of this data structure.

name

The name of the task.

queueName

A four-byte code indicating the status of the queue waiting on the task.

runState

The current state of the task (running, ready, or blocked).

lastCPU

The address of the last processor that ran this task.

weight

The weighting assigned to this task.

processID

The ID of the process that owns this task.

cpuTime

The accumulated CPU time used by the task.

schedTime

The time when the task was last scheduled.

creationTime

The time when the task was created.

codePageFaults

The number of page faults that occurred during code execution.

dataPageFaults

The number of page faults that occurred during data access.

preemptions

The number of times this task was preempted.

cpuID

The ID of the last processor that ran this task.

blockedObject

Reserved for use by OS X.

spaceID

Address space ID of this task.

stackBase

The lowest memory address of the task’s stack.

stackLimit

The highest memory address of the task’s stack.

stackCurr

The current stack address.

Discussion

If you specify the kMPTaskStateTaskInfo constant when calling the function MPExtractTaskState , Multiprocessing Services returns state information in an MPTaskInfo structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPTaskInfoVersion2

struct MPTaskInfoVersion2 {
   PBVersion version;
   OSType name;
   OSType queueName;
   UInt16 runState;
   UInt16 lastCPU;
   UInt32 weight;
   MPProcessID processID;
   AbsoluteTime cpuTime;
   AbsoluteTime schedTime;
   AbsoluteTime creationTime;
   ItemCount codePageFaults;
   ItemCount dataPageFaults;
   ItemCount preemptions;
   MPCpuID cpuID;
};
typedef struct MPTaskInfoVersion2 MPTaskInfoVersion2;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPTaskStateKind

typedef UInt32 MPTaskStateKind;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPTaskWeight

Represents the relative processor weighting of a task.

typedef UInt32 MPTaskWeight;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

MPTimerID

Represents a timer ID.

typedef struct OpaqueMPTimerID * MPTimerID;
Discussion

You obtain a timer ID by calling the function MPCreateTimer.

Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

TaskStorageIndex

Represents a task storage index value used by functions described in “Accessing Per-Task Storage Variables.”

typedef ItemCount TaskStorageIndex;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

TaskStorageValue

Represents a task storage value used by functions described in “Accessing Per-Task Storage Variables.”

typedef LogicalAddress TaskStorageValue;
Availability
  • Available in OS X v10.0 and later.
Declared In
Multiprocessing.h

Constants

Allocation constants

The maximum memory allocation size.

enum {
   kMPMaxAllocSize = 1024L * 1024 * 1024
};
Constants
kMPMaxAllocSize

The maximum allocation size: 1GB.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Task IDs

Use to specify no task ID.

enum {
   kMPNoID = kInvalidID
};
Constants
kMPNoID

No task ID.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Discussion

Used when calling MPTaskIsPreemptive if you want to specify the current task.

Data Structure Version Constants

Data structure version information constants.

enum {
   kMPQueueInfoVersion = 1L | (kOpaqueQueueID << 16),
   kMPSemaphoreInfoVersion = 1L | (kOpaqueSemaphoreID << 16),
   kMPEventInfoVersion = 1L | (kOpaqueEventID << 16),
   kMPCriticalRegionInfoVersion = 1L | (kOpaqueCriticalRegionID << 16),
   kMPNotificationInfoVersion = 1L | (kOpaqueNotificationID << 16),
   kMPAddressSpaceInfoVersion = 1L | (kOpaqueAddressSpaceID << 16)
};
Constants
kMPQueueInfoVersion

The MPQueueInfo structure version.

Available in OS X v10.0 and later.

Declared in MultiprocessingInfo.h.

kMPSemaphoreInfoVersion

The MPSemaphoreInfo structure version.

Available in OS X v10.0 and later.

Declared in MultiprocessingInfo.h.

kMPEventInfoVersion

The MPEventInfo structure version.

Available in OS X v10.0 and later.

Declared in MultiprocessingInfo.h.

kMPCriticalRegionInfoVersion

The MPCriticalRegionInfo structure version.

Available in OS X v10.0 and later.

Declared in MultiprocessingInfo.h.

kMPNotificationInfoVersion

The MPNotificationInfo structure version.

Available in OS X v10.0 and later.

Declared in MultiprocessingInfo.h.

kMPAddressSpaceInfoVersion

The MPAddressSpaceInfo structure version.

Available in OS X v10.1 and later.

Declared in MultiprocessingInfo.h.

Values for the MPOpaqueIDClass type

Constants indicating the source of a generic notification.

enum {
   kOpaqueAnyID = 0,
   kOpaqueProcessID = 1,
   kOpaqueTaskID = 2,
   kOpaqueTimerID = 3,
   kOpaqueQueueID = 4,
   kOpaqueSemaphoreID = 5,
   kOpaqueCriticalRegionID = 6,
   kOpaqueCpuID = 7,
   kOpaqueAddressSpaceID = 8,
   kOpaqueEventID = 9,
   kOpaqueCoherenceID = 10,
   kOpaqueAreaID = 11,
   kOpaqueNotificationID = 12,
   kOpaqueConsoleID = 13
};
Constants
kOpaqueAnyID

Any source.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueProcessID

A process.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueTaskID

A task.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueTimerID

A timer.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueQueueID

A queue.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueSemaphoreID

A semaphore.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueCriticalRegionID

A critical region.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueCpuID

A CPU.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueAddressSpaceID

An address space.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueEventID

An event.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueCoherenceID

A coherence group.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueAreaID

An area.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueNotificationID

A notification.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kOpaqueConsoleID

A console.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Memory Allocation Alignment Constants

Specify the alignment of the desired memory block when calling the MPAllocateAligned function.

enum {
   kMPAllocateDefaultAligned = 0,
   kMPAllocate8ByteAligned = 3,
   kMPAllocate16ByteAligned = 4,
   kMPAllocate32ByteAligned = 5,
   kMPAllocate1024ByteAligned = 10,
   kMPAllocate4096ByteAligned = 12,
   kMPAllocateMaxAlignment = 16,
   kMPAllocateAltiVecAligned = kMPAllocate16ByteAligned,
   kMPAllocateVMXAligned = kMPAllocateAltiVecAligned,
   kMPAllocateVMPageAligned = 254,
   kMPAllocateInterlockAligned = 255
};
Constants
kMPAllocateDefaultAligned

Use the default alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocate8ByteAligned

Use 8-byte alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocate16ByteAligned

Use 16-byte alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocate32ByteAligned

Use 32-byte alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocate1024ByteAligned

Use 1024-byte alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocate4096ByteAligned

Use 4096-byte alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateMaxAlignment

Use the maximum alignment (65536 byte).

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateAltiVecAligned

Use AltiVec alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateVMXAligned

Use VMX (now called AltiVec) alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateVMPageAligned

Use virtual memory page alignment. This alignment is set at runtime.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateInterlockAligned

Use interlock alignment, which is the alignment needed to allow the use of CPU interlock instructions (that is, lwarx and stwcx.) on the returned memory address. This alignment is set at runtime. In most cases you would never need to use this alignment.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Memory Allocation Option Constants

Specify optional actions when calling the MPAllocateAligned function.

enum {
   kMPAllocateClearMask = 0x0001,
   kMPAllocateGloballyMask = 0x0002,
   kMPAllocateResidentMask = 0x0004,
   kMPAllocateNoGrowthMask = 0x0010,
   kMPAllocateNoCreateMask = 0x0020
};
Constants
kMPAllocateClearMask

Zero out the allocated memory block.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateGloballyMask

Allocate memory from in memory space that is visible to all processes. Note that such globally-allocated space is not automatically reclaimed when the allocating process terminates. By default, MPAllocateAligned allocates memory from process-specific (that is, not global) memory.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateResidentMask

Allocate memory from resident memory only (that is, the allocated memory is not pageable).

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateNoGrowthMask

Do not attempt to grow the pool of available memory. Specifying this option is useful, as attempting to grow memory may cause your task to block until such memory becomes available.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPAllocateNoCreateMask

Do not attempt to create the pool if it does not yet exist.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

MPDebuggerLevel

Indicates the debugger level.

typedef UInt32 MPDebuggerLevel;
enum {
   kMPLowLevelDebugger = 0x00000000,
   kMPMidLevelDebugger = 0x10000000,
   kMPHighLevelDebugger = 0x20000000
};
Constants
kMPLowLevelDebugger

The low-level debugger.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

kMPMidLevelDebugger

The mid-level debugger.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

kMPHighLevelDebugger

The high-level debugger.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

Library Version Constants

Identifies the current library version.

enum {
   MPLibrary_MajorVersion = 2,
   MPLibrary_MinorVersion = 3,
   MPLibrary_Release = 1,
   MPLibrary_DevelopmentRevision = 1
};
Constants
MPLibrary_MajorVersion

Major version number.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

MPLibrary_MinorVersion

Minor version number.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

MPLibrary_Release

Release number.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

MPLibrary_DevelopmentRevision

Development revision number.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Remote Call Context Option Constants

Specify which contexts are allowed to execute the callback function when using MPRemoteCall.

enum {
   kMPAnyRemoteContext = 0,
   kMPOwningProcessRemoteContext = 1,
   kMPInterruptRemoteContext = 2,
   kMPAsyncInterruptRemoteContext = 3
};
typedef UInt8 MPRemoteContext;
Constants
kMPAnyRemoteContext

Any cooperative context can execute the function. Note that the called function may not have access to any of the owning context’s process-specific low-memory values.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPOwningProcessRemoteContext

Only the context that owns the task can execute the function.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPInterruptRemoteContext

Unsupported in OS X.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

kMPAsyncInterruptRemoteContext

Unsupported in OS X.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

Discussion

These constants are used to support older versions of Mac OS and are ignored in OS X.

Task Creation Options

Specify optional actions when calling the MPCreateTask function.

enum {
   kMPCreateTaskSuspendedMask = 1L << 0,
   kMPCreateTaskTakesAllExceptionsMask = 1L << 1,
   kMPCreateTaskNotDebuggableMask = 1L << 2,
   kMPCreateTaskValidOptionsMask = kMPCreateTaskSuspendedMask | kMPCreateTaskTakesAllExceptionsMask | kMPCreateTaskNotDebuggableMask
};
typedef OptionBits MPTaskOptions;
Constants
kMPCreateTaskSuspendedMask

Unsupported in OS X.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPCreateTaskTakesAllExceptionsMask

The task will take all exceptions, including those normally handled by the system, such as page faults.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPCreateTaskNotDebuggableMask

Unsupported in OS X.

Available in OS X v10.1 and later.

Declared in Multiprocessing.h.

kMPCreateTaskValidOptionsMask

Include all valid options for this task.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Task Exception Disposal Constants

Specify actions to take on an exception when passed in the action parameter of the MPDisposeTaskException function.

enum {
   kMPTaskPropagate = 0,
   kMPTaskResumeStep = 1,
   kMPTaskResumeBranch = 2,
   kMPTaskResumeMask = 0x0000,
   kMPTaskPropagateMask = 1 << kMPTaskPropagate,
   kMPTaskResumeStepMask = 1 << kMPTaskResumeStep,
   kMPTaskResumeBranchMask = 1 << kMPTaskResumeBranch
};
Constants
kMPTaskPropagate

The exception is propagated.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskResumeStep

The task is resumed and single step is enabled.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskResumeBranch

The task is resumed and branch stepping is enabled.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskResumeMask

Resume the task.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskPropagateMask

Propagate the exception to the next debugger level.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskResumeStepMask

Resume the task and enable single stepping.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskResumeBranchMask

Resume the task and enable branch stepping.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Task Information Structure Version Constant

Indicates the current version of the MPTaskInfo structure (returned as the first field).

enum {
   kMPTaskInfoVersion = 3
};
Constants
kMPTaskInfoVersion

The current version of the task information structure.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Task Run State Constants

Indicate the state of the task when returned as part of the MPTaskInfo data structure.

enum {
   kMPTaskBlocked = 0,
   kMPTaskReady = 1,
   kMPTaskRunning = 2
};
Constants
kMPTaskBlocked

The task is blocked..

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskReady

The task is ready for execution.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskRunning

The task is currently running.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Task State Constants

Specify what states you want to set or obtain when calling the MPExtractTaskState or MPSetTaskState functions.

enum {
   kMPTaskStateRegisters = 0,
   kMPTaskStateFPU = 1,
   kMPTaskStateVectors = 2,
   kMPTaskStateMachine = 3,
   kMPTaskState32BitMemoryException = 4,
   kMPTaskStateTaskInfo = 5
};
Constants
kMPTaskStateRegisters

The task’s general-purpose (GP) registers. The RegisterInformationPowerPC structure in MachineExceptions.h defines the format of this information.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskStateFPU

The task’s floating point registers. The FPUInformationPowerPC structure in MachineExceptions.h defines the format of this information.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskStateVectors

The task’s vector registers. The VectorInformationPowerPC structure in MachineExceptions.h defines the format of this information.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskStateMachine

The task’s machine registers. The MachineInformationPowerPC structure in MachineExceptions.h defines the format of this information. Note that the MSR, ExceptKind, DSISR, and DAR registers are read-only.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskState32BitMemoryException

The task’s exception information for older 32-bit memory exceptions (that is, memory exceptions on 32-bit CPUs). The MemoryExceptionInformation structure in MachineExceptions.h defines the format of this information. This exception information is read-only.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTaskStateTaskInfo

Static and dynamic information about the task, as described by the data structure MPTaskInfo. This task information is read-only.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Timer Duration Constants

Specify the maximum time a task should wait for an event to occur.

enum {
   kDurationImmediate = 0,
   kDurationForever = 0x7FFFFFFF,
   kDurationMillisecond = 1,
   kDurationMicrosecond = -1
};
Constants
kDurationImmediate

The task times out immediately, whether or not the event has occurred. If the event occurred, the return status is noErr. If the event did not occur, the return status is kMPTimeoutErr (assuming no other errors occurred).

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kDurationForever

The task waits forever. The blocking call waits until either the event occurs, or until the object being waited upon (such as a message queue) is deleted.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kDurationMillisecond

The task waits one millisecond before timing out.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kDurationMicrosecond

The task waits one microsecond before timing out.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Discussion

You can use these constants in conjunction with other values to indicate specific wait intervals. For example, to wait 1 second, you can pass kDurationMillisecond * 1000.

Timer Option Masks

Indicate optional actions when calling MPArmTimer.

enum {
   kMPPreserveTimerIDMask = 1L << 0,
   kMPTimeIsDeltaMask = 1L << 1,
   kMPTimeIsDurationMask = 1L << 2
};
Constants
kMPPreserveTimerIDMask

Specifying this mask prevents the timer from being deleted when it expires.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTimeIsDeltaMask

Specifying this mask indicates that the specified time should be added to the previous expiration time to form the new expiration time. You can use this mask to compensate for timing drift caused by the finite amount of time required to arm the timer, receive the notification, and so on.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

kMPTimeIsDurationMask

Specifying this mask indicates that the specified expiration time is of type Duration. You can use this mask to avoid having to call time conversion routines when specifying an expiration time.

Available in OS X v10.0 and later.

Declared in Multiprocessing.h.

Result Codes

Result codes defined for Multiprocessing Services are listed below.

Result CodeValueDescription
kMPIterationEndErr-29275

Available in OS X v10.0 and later.

kMPPrivilegedErr-29276

Available in OS X v10.0 and later.

kMPProcessCreatedErr-29288

Available in OS X v10.0 and later.

kMPProcessTerminatedErr-29289

Available in OS X v10.0 and later.

kMPTaskCreatedErr-29290

Available in OS X v10.0 and later.

kMPTaskBlockedErr -29291

The desired task is blocked.

Available in OS X v10.0 and later.

kMPTaskStoppedErr -29292

The desired task is stopped.

Available in OS X v10.0 and later.

kMPDeletedErr -29295

The desired notification the function was waiting upon was deleted.

Available in OS X v10.0 and later.

kMPTimeoutErr -29296

The designated timeout interval passed before the function could take action.

Available in OS X v10.0 and later.

kMPInsufficientResourcesErr -29298

Could not complete task due to unavailable Multiprocessing Services resources. Note that many functions return this value as a general error when the desired action could not be performed.

Available in OS X v10.0 and later.

kMPInvalidIDErr -29299

Invalid ID value. For example, an invalid message queue ID was passed to MPNotifyQueue.

Available in OS X v10.0 and later.

Gestalt Constants

You can determine which system software calls are preemptively-safe for Multiprocessing Services by using the preemptive function attribute selectors defined in the Gestalt Manager. For more information, see Gestalt Manager Reference.