Class

NSPort

An abstract class that represents a communication channel.

Overview

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

Topics

Creating Instances

allocWithZone:

Returns an instance of the NSMachPort class.

port

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

Validation

invalidate

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

valid

A Boolean value that indicates whether the receiver is valid.

Setting the Delegate

setDelegate:

Sets the receiver’s delegate to a given object.

delegate

Returns the receiver’s delegate.

Creating Connections

addConnection:toRunLoop:forMode:

Adds the receiver to the list of ports monitored by a given run loop for the given input mode.

Deprecated
removeConnection:fromRunLoop:forMode:

Removes the receiver from the list of ports monitored by runLoop in the given input mode, mode.

Deprecated

Setting Information

sendBeforeDate:components:from:reserved:

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

sendBeforeDate:msgid:components:from:reserved:

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

reservedSpaceLength

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

Port Monitoring

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.

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.

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.

Data Types

NSSocketNativeHandle

Type for the platform-specific native socket handle.

Relationships

Inherits From

Conforms To

See Also

Sockets

NSHost

A representation of an individual host on the network.

NSSocketPort

A port that represents a BSD socket.