iOS Developer Library

Developer

Foundation Framework Reference NSPort Class Reference

Options
Deployment Target:

On This Page
Language:

NSPort

Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

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.

  • allocWithZone: + allocWithZone: Available in iOS 2.0 through iOS 4.3

    Returns an instance of the NSMachPort class.

    Declaration

    Objective-C

    + (id)allocWithZone:(NSZone *)zone

    Parameters

    zone

    The memory zone in which to allocate the new object.

    Return Value

    An instance of the NSMachPort class.

    Discussion

    For backward compatibility on Mach, allocWithZone: returns an instance of the NSMachPort class when sent to the NSPort class. Otherwise, it returns an instance of a concrete subclass that can be used for messaging between threads or processes on the local machine, or, in the case of NSSocketPort, between processes on separate machines.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 through iOS 4.3.

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

    Declaration

    Objective-C

    + (NSPort *)port

    Return Value

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func invalidate()

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    valid

  • valid valid Property

    A Boolean value that indicates whether the receiver is valid. (read-only)

    Declaration

    Swift

    var valid: Bool { get }

    Objective-C

    @property(readonly, getter=isValid) BOOL valid

    Discussion

    NOfalse if the receiver is known to be invalid, otherwise YEStrue.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

    See Also

    – invalidate

  • Sets the receiver’s delegate to a given object.

    Declaration

    Swift

    func setDelegate(_ anObject: NSPortDelegate?)

    Objective-C

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

    Parameters

    anObject

    The delegate for the receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – delegate

  • Returns the receiver’s delegate.

    Declaration

    Swift

    func delegate() -> NSPortDelegate?

    Objective-C

    - (id<NSPortDelegate>)delegate

    Return Value

    The receiver’s delegate.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func sendBeforeDate(_ limitDate: NSDate, components components: NSMutableArray, from receivePort: NSPort, reserved headerSpaceReserved: Int) -> Bool

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func sendBeforeDate(_ limitDate: NSDate, msgid msgID: Int, components components: NSMutableArray, from receivePort: NSPort, reserved headerSpaceReserved: Int) -> Bool

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The number of bytes of space reserved by the receiver for sending data. (read-only)

    Declaration

    Swift

    var reservedSpaceLength: Int { get }

    Objective-C

    @property(readonly) NSUInteger reservedSpaceLength

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func removeFromRunLoop(_ runLoop: NSRunLoop, forMode mode: String)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func scheduleInRunLoop(_ runLoop: NSRunLoop, forMode mode: String)

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.