---

NSMachPort Class Reference

Overview

NSMachPort is a subclass of NSPort that can be used as an endpoint for distributed object connections (or raw messaging). NSMachPort is an object wrapper for a Mach port, the fundamental communication port in Mac OS X. NSMachPort allows for local (on the same machine) communication only. A companion class, NSSocketPort, allows for both local and remote distributed object communication, but may be more expensive than NSMachPort for the local case.

To use NSMachPort effectively, you should be familiar with Mach ports, port access rights, and Mach messages. See the Mach OS documentation for more information.

Tasks

Creating and Initializing

• + portWithMachPort:
• + portWithMachPort:options:
• – initWithMachPort:
• – initWithMachPort:options:

Getting the Mach Port

• – machPort

Scheduling the Port on a Run Loop

• – removeFromRunLoop:forMode:
• – scheduleInRunLoop:forMode:

Handling Mach Messages

• – handleMachMessage:  delegate method

Class Methods

portWithMachPort:

Creates and returns a port object configured with the given Mach port.

+ (NSPort *)portWithMachPort:(uint32_t)machPort

Parameters

machPort

The Mach port for the new port. This parameter should originally be of type mach_port_t.

Return Value

An NSMachPort object that uses machPort to send or receive messages.

Discussion

Creates the port object if necessary. Depending on the access rights associated with machPort, the new port object may be usable only for sending messages.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSPort.h

portWithMachPort:options:

Creates and returns a port object configured with the specified options and the given Mach port.

+ (NSPort *)portWithMachPort:(uint32_t)machPort options:(NSUInteger)options

Parameters

machPort

The Mach port for the new port. This parameter should originally be of type mach_port_t.

options

Specifies options for what to do with the underlying port rights when the NSMachPort object is invalidated or destroyed. For a list of constants, see “Mach Port Rights.”

Return Value

An NSMachPort object that uses machPort to send or receive messages.

Discussion

Creates the port object if necessary. Depending on the access rights associated with machPort, the new port object may be usable only for sending messages.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSPort.h

Instance Methods

initWithMachPort:

Initializes a newly allocated NSMachPort object with a given Mach port.

- (id)initWithMachPort:(uint32_t)machPort

Parameters

machPort

The Mach port for the new port. This parameter should originally be of type mach_port_t.

Return Value

Returns an initialized NSMachPort object that uses machPort to send or receive messages. The returned object might be different than the original receiver

Discussion

Depending on the access rights for machPort, the new port may be able to only send messages. If a port with machPort already exists, this method deallocates the receiver, then retains and returns the existing port.

This method is the designated initializer for the NSMachPort class.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSPort.h

initWithMachPort:options:

Initializes a newly allocated NSMachPort object with a given Mach port and the specified options.

- (id)initWithMachPort:(uint32_t)machPort options:(NSUInteger)options

Parameters

machPort

The Mach port for the new port. This parameter should originally be of type mach_port_t.

options

Specifies options for what to do with the underlying port rights when the NSMachPort object is invalidated or destroyed. For a list of constants, see “Mach Port Rights.”

Return Value

Returns an initialized NSMachPort object that uses machPort to send or receive messages. The returned object might be different than the original receiver

Discussion

Depending on the access rights for machPort, the new port may be able to only send messages. If a port with machPort already exists, this method deallocates the receiver, then retains and returns the existing port.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSPort.h

machPort

Returns as an int the Mach port used by the receiver.

- (uint32_t)machPort

Return Value

The Mach port used by the receiver. Cast this value to a mach_port_t when using it with Mach system calls.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSPort.h

removeFromRunLoop:forMode:

Removes the receiver from the run loop mode mode of runLoop.

- (void)removeFromRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

Parameters

runLoop

The run loop from which to remove the receiver.

mode

The run loop mode from which to remove the receiver.

Discussion

When the receiver is removed, the run loop stops monitoring the Mach port for incoming messages.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – scheduleInRunLoop:forMode:

Declared In

NSPort.h

scheduleInRunLoop:forMode:

Schedules the receiver into the run loop mode mode of runLoop.

- (void)scheduleInRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

Parameters

runLoop

The run loop to which to add the receiver.

mode

The run loop mode in which to add the receiver.

Discussion

When the receiver is scheduled, the run loop monitors the mach port for incoming messages and, when a message arrives, invokes the delegate method handleMachMessage:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeFromRunLoop:forMode:

Declared In

NSPort.h

Delegate Methods

handleMachMessage:

Process an incoming Mach message.

- (void)handleMachMessage:(void *)machMessage

Parameters

machMessage

A pointer to a Mach message, cast as a pointer to void.

Discussion

The delegate should interpret this data as a pointer to a Mach message beginning with a msg_header_t structure and should handle the message appropriately.

The delegate should implement only one of handleMachMessage: and handlePortMessage:.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSPort.h

Constants

Mach Port Rights

Used to remove access rights to a mach port when the NSMachPort object is invalidated or destroyed.

enum {
   NSMachPortDeallocateNone = 0,
   NSMachPortDeallocateSendRight = (1 << 0),
   NSMachPortDeallocateReceiveRight = (1 << 1)
};

Constants

NSMachPortDeallocateNone

Do not remove any send or receive rights.

Available in Mac OS X v10.5 and later.

Declared in NSPort.h.

NSMachPortDeallocateSendRight

Deallocate a send right when the NSMachPort object is invalidated or destroyed.

Available in Mac OS X v10.5 and later.

Declared in NSPort.h.

NSMachPortDeallocateReceiveRight

Remove a receive right when the NSMachPort object is invalidated or destroyed.

Available in Mac OS X v10.5 and later.

Declared in NSPort.h.

Declared In

NSPort.h

---