NSMachPort Class Reference

Inherits from
NSPort : NSObject
Conforms to
NSCoding (NSPort)
NSCopying (NSPort)
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Distributed Objects Programming Topics
Declared in
NSPort.h
Related sample code

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 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

Getting the Mach Port

Scheduling the Port on a Run Loop

Getting and Setting the Delegate

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 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 OS X v10.5 and later.
Declared In
NSPort.h

Instance Methods

delegate

Returns the receiver’s delegate.

- (id < NSMachPortDelegate >)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSPort.h

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 OS X v10.0 and later.
Related Sample Code
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 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 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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
See Also
Declared In
NSPort.h

setDelegate:

Sets the receiver’s delegate to a given object.

- (void)setDelegate:(id < NSMachPortDelegate >)anObject
Parameters
anObject

The delegate for the receiver.

Availability
  • Available in OS X v10.6 and later.
See Also
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 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 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 OS X v10.5 and later.

Declared in NSPort.h.



© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-04-13)

Did this document help you? Yes It's good, but... Not helpful...