NSPort Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Declared in
NSPort.h
Companion guides
Distributed Objects Programming Topics
Threading Programming Guide

Overview

NSPort is an abstract class that represents a communication channel. Communication occurs between NSPort objects, which typically reside in different threads or tasks. The distributed objects system uses NSPort objects to send NSPortMessage objects back and forth. You should implement interapplication communication using distributed objects whenever possible and use NSPort objects only when necessary.

To receive incoming messages, NSPort objects must be added to an NSRunLoop object as input sources. NSConnection objects automatically add their receive port when initialized.

When an NSPort object receives a port message, it forwards the message to its delegate in a handleMachMessage: or handlePortMessage: message. The delegate should implement only one of these methods to process the incoming message in whatever form desired. handleMachMessage: provides a message as a raw Mach message beginning with a msg_header_t structure. handlePortMessage: provides a message as an NSPortMessage object, which is an object-oriented wrapper for a Mach message. If a delegate has not been set, the NSPort object handles the message itself.

When you are finished using a port object, you must explicitly invalidate the port object prior to sending it a release message. Similarly, if your application uses garbage collection, you must invalidate the port object before removing any strong references to it. If you do not invalidate the port, the resulting port object may linger and create a memory leak. To invalidate the port object, invoke its invalidate method.

Foundation defines three concrete subclasses of NSPort. NSMachPort and NSMessagePort allow local (on the same machine) communication only. NSSocketPort allows for both local and remote communication, but may be more expensive than the others for the local case. When creating an NSPort object, using allocWithZone: or port, an NSMachPort object is created instead.

Adopted Protocols

NSCoding
NSCopying

Tasks

Creating Instances

Validation

Setting the Delegate

Setting Information

Port Monitoring

Class Methods

port

Creates and returns a new NSPort object capable of both sending and receiving messages.

+ (NSPort *)port
Return Value

A new NSPort object capable of both sending and receiving messages.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

Instance Methods

delegate

Returns the receiver’s delegate.

- (id < NSPortDelegate >)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

invalidate

Marks the receiver as invalid and posts an NSPortDidBecomeInvalidNotification to the default notification center.

- (void)invalidate
Discussion

You must call this method before releasing a port object (or removing strong references to it if your application is garbage collected).

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSPort.h

isValid

Returns a Boolean value that indicates whether the receiver is valid.

- (BOOL)isValid
Return Value

NO if the receiver is known to be invalid, otherwise YES.

Discussion

An NSPort object becomes invalid when its underlying communication resource, which is operating system dependent, is closed or damaged.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

removeFromRunLoop:forMode:

This method should be implemented by a subclass to stop monitoring of a port when removed from a give run loop in a given input mode.

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

This method should not be called directly.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

reservedSpaceLength

Returns the number of bytes of space reserved by the receiver for sending data.

- (NSUInteger)reservedSpaceLength
Return Value

The number of bytes reserved by the receiver for sending data. The default length is 0.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

scheduleInRunLoop:forMode:

This method should be implemented by a subclass to set up monitoring of a port when added to a given run loop in a given input mode.

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

The run loop to which to add the receiver.

mode

The run loop mode to which to add the receiver

Discussion

This method should not be called directly.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

sendBeforeDate:components:from:reserved:

This method is provided for subclasses that have custom types of NSPort.

- (BOOL)sendBeforeDate:(NSDate *)limitDate components:(NSMutableArray *)components from:(NSPort *)receivePort reserved:(NSUInteger)headerSpaceReserved
Parameters
limitDate

The last instant that a message may be sent.

components

The message components.

receivePort

The receive port.

headerSpaceReserved

The number of bytes reserved for the header.

Discussion

NSConnection calls this method at the appropriate times. This method should not be called directly. This method could raise an NSInvalidSendPortException, NSInvalidReceivePortException, or an NSPortSendException, depending on the type of send port and the type of error.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

sendBeforeDate:msgid:components:from:reserved:

This method is provided for subclasses that have custom types of NSPort.

- (BOOL)sendBeforeDate:(NSDate *)limitDate msgid:(NSUInteger)msgID components:(NSMutableArray *)components from:(NSPort *)receivePort reserved:(NSUInteger)headerSpaceReserved
Parameters
limitDate

The last instant that a message may be sent.

msgID

The message ID.

components

The message components.

receivePort

The receive port.

headerSpaceReserved

The number of bytes reserved for the header.

Discussion

NSConnection calls this method at the appropriate times. This method should not be called directly. This method could raise an NSInvalidSendPortException, NSInvalidReceivePortException, or an NSPortSendException, depending on the type of send port and the type of error.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSPort.h

setDelegate:

Sets the receiver’s delegate to a given object.

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

The delegate for the receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSPort.h

Notifications

NSPortDidBecomeInvalidNotification

Posted from the invalidate method, which is invoked when the NSPort is deallocated or when it notices that its communication channel has been damaged. The notification object is the NSPort object that has become invalid. This notification does not contain a userInfo dictionary.

An NSSocketPort object cannot detect when its connection to a remote port is lost, even if the remote port is on the same machine. Therefore, it cannot invalidate itself and post this notification. Instead, you must detect the timeout error when the next message is sent.

The NSPort object posting this notification is no longer useful, so all receivers should unregister themselves for any notifications involving the NSPort. A method receiving this notification should check to see which port became invalid before attempting to do anything. In particular, observers that receive all NSPortDidBecomeInvalidNotification messages should be aware that communication with the window server is handled through an NSPort. If this port becomes invalid, drawing operations will cause a fatal error.

Availability
Declared In
NSPort.h