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 |
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
Tasks
Creating Instances
-
+ port -
+ allocWithZone:Available in iOS 2.0 through iOS 4.3
Validation
Setting the Delegate
Setting Information
-
– sendBeforeDate:components:from:reserved: -
– sendBeforeDate:msgid:components:from:reserved: -
– reservedSpaceLength
Port Monitoring
Class Methods
port
Creates and returns a new NSPort object capable of both sending and receiving messages.
Return Value
A new NSPort object capable of both sending and receiving messages.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPort.hInstance Methods
delegate
Returns the receiver’s delegate.
Return Value
The receiver’s delegate.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPort.hinvalidate
Marks the receiver as invalid and posts an NSPortDidBecomeInvalidNotification to the default notification center.
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.hisValid
Returns a Boolean value that indicates whether the receiver is valid.
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.
See Also
Declared In
NSPort.hremoveFromRunLoop: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.
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.
See Also
Declared In
NSPort.hreservedSpaceLength
Returns the number of bytes of space reserved by the receiver for sending data.
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.hscheduleInRunLoop: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.
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.
See Also
Declared In
NSPort.hsendBeforeDate:components:from:reserved:
This method is provided for subclasses that have custom types of NSPort.
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.hsendBeforeDate:msgid:components:from:reserved:
This method is provided for subclasses that have custom types of NSPort.
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.hsetDelegate:
Sets the receiver’s delegate to a given object.
Parameters
- anObject
The delegate for the receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPort.hNotifications
NSPortDidBecomeInvalidNotification
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
- Available in iOS 2.0 and later.
Declared In
NSPort.h© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-04-13)