iOS Developer Library

Developer

Foundation Framework Reference NSThread Class Reference

Options
Deployment Target:

On This Page
Language:

NSThread

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.

An NSThread object controls a thread of execution. Use this class when you want to have an Objective-C method run in its own thread of execution. Threads are especially useful when you need to perform a lengthy task, but don’t want it to block the execution of the rest of the application. In particular, you can use threads to avoid blocking the main thread of the application, which handles user interface and event-related actions. Threads can also be used to divide a large job into several smaller jobs, which can lead to performance increases on multi-core computers.

Prior to OS X v10.5, the only way to start a new thread is to use the detachNewThreadSelector:toTarget:withObject: method. In OS X v10.5 and later, you can create instances of NSThread and start them at a later time using the start method.

In OS Xv10.5, the NSThread class supports semantics similar to those of NSOperation for monitoring the runtime condition of a thread. You can use these semantics to cancel the execution of a thread or determine if the thread is still executing or has finished its task. Canceling a thread requires support from your thread code; see the description for cancel for more information.

Subclassing Notes

In OS X v10.5 and later, you can subclass NSThread and override the main method to implement your thread’s main entry point. If you override main, you do not need to invoke the inherited behavior by calling super.

  • init() - init Designated Initializer

    Returns an initialized NSThread object.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    An initialized NSThread object.

    Discussion

    This is the designated initializer for NSThread.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSThread object initialized with the given arguments.

    Declaration

    Swift

    convenience init(target target: AnyObject, selector selector: Selector, object argument: AnyObject?)

    Objective-C

    - (instancetype)initWithTarget:(id)target selector:(SEL)selector object:(id)argument

    Parameters

    target

    The object to which the message specified by selector is sent.

    selector

    The selector for the message to send to target. This selector must take only one argument and must not have a return value.

    argument

    The single argument passed to the target. May be nil.

    Return Value

    An NSThread object initialized with the given arguments.

    Discussion

    The objects target and argument are retained during the execution of the detached thread. They are released when the thread finally exits.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Detaches a new thread and uses the specified selector as the thread entry point.

    Declaration

    Swift

    class func detachNewThreadSelector(_ aSelector: Selector, toTarget aTarget: AnyObject, withObject anArgument: AnyObject?)

    Objective-C

    + (void)detachNewThreadSelector:(SEL)aSelector toTarget:(id)aTarget withObject:(id)anArgument

    Parameters

    aSelector

    The selector for the message to send to the target. This selector must take only one argument and must not have a return value.

    aTarget

    The object that will receive the message aSelector on the new thread.

    anArgument

    The single argument passed to the target. May be nil.

    Discussion

    The objects aTarget and anArgument are retained during the execution of the detached thread, then released. The detached thread is exited (using the exit class method) as soon as aTarget has completed executing the aSelector method.

    If this thread is the first thread detached in the application, this method posts the NSWillBecomeMultiThreadedNotification with object nil to the default notification center.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Starts the receiver.

    Declaration

    Swift

    func start()

    Objective-C

    - (void)start

    Discussion

    This method spawns the new thread and invokes the receiver’s main method on the new thread. If you initialized the receiver with a target and selector, the default main method invokes that selector automatically.

    If this thread is the first thread detached in the application, this method posts the NSWillBecomeMultiThreadedNotification with object nil to the default notification center.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The main entry point routine for the thread.

    Declaration

    Swift

    func main()

    Objective-C

    - (void)main

    Discussion

    The default implementation of this method takes the target and selector used to initialize the receiver and invokes the selector on the specified target. If you subclass NSThread, you can override this method and use it to implement the main body of your thread instead. If you do so, you do not need to invoke super.

    You should never invoke this method directly. You should always start your thread by invoking the start method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – start

  • Blocks the current thread until the time specified.

    Declaration

    Swift

    class func sleepUntilDate(_ aDate: NSDate)

    Objective-C

    + (void)sleepUntilDate:(NSDate *)aDate

    Parameters

    aDate

    The time at which to resume processing.

    Discussion

    No run loop processing occurs while the thread is blocked.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Sleeps the thread for a given time interval.

    Declaration

    Swift

    class func sleepForTimeInterval(_ ti: NSTimeInterval)

    Objective-C

    + (void)sleepForTimeInterval:(NSTimeInterval)ti

    Parameters

    ti

    The duration of the sleep.

    Discussion

    No run loop processing occurs while the thread is blocked.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Terminates the current thread.

    Declaration

    Swift

    class func exit()

    Objective-C

    + (void)exit

    Discussion

    This method uses the currentThread class method to access the current thread. Before exiting the thread, this method posts the NSThreadWillExitNotification with the thread being exited to the default notification center. Because notifications are delivered synchronously, all observers of NSThreadWillExitNotification are guaranteed to receive the notification before the thread exits.

    Invoking this method should be avoided as it does not give your thread a chance to clean up any resources it allocated during its execution.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Changes the cancelled state of the receiver to indicate that it should exit.

    Declaration

    Swift

    func cancel()

    Objective-C

    - (void)cancel

    Discussion

    The semantics of this method are the same as those used for the NSOperation object. This method sets state information in the receiver that is then reflected by the isCancelled method. Threads that support cancellation should periodically call the isCancelled method to determine if the thread has in fact been cancelled, and exit if it has been.

    For more information about cancellation and operation objects, see NSOperation Class Reference.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – isCancelled

  • executing executing Property

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

    Declaration

    Swift

    var executing: Bool { get }

    Objective-C

    @property(readonly, getter=isExecuting) BOOL executing

    Discussion

    YEStrue if the receiver is executing, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • finished finished Property

    A Boolean value that indicates whether the receiver has finished execution. (read-only)

    Declaration

    Swift

    var finished: Bool { get }

    Objective-C

    @property(readonly, getter=isFinished) BOOL finished

    Discussion

    YEStrue if the receiver has finished execution, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • cancelled cancelled Property

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

    Declaration

    Swift

    var cancelled: Bool { get }

    Objective-C

    @property(readonly, getter=isCancelled) BOOL cancelled

    Discussion

    YEStrue if the receiver has been cancelled, otherwise NOfalse.

    If your thread supports cancellation, it should check this property periodically and exit if it ever returns YEStrue.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a Boolean value that indicates whether the current thread is the main thread.

    Declaration

    Swift

    class func isMainThread() -> Bool

    Objective-C

    + (BOOL)isMainThread

    Return Value

    YEStrue if the current thread is the main thread, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    + mainThread

  • A Boolean value that indicates whether the receiver is the main thread. (read-only)

    Declaration

    Swift

    var isMainThread: Bool { get }

    Objective-C

    @property(readonly) BOOL isMainThread

    Discussion

    YEStrue if the receiver is the main thread, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the NSThread object representing the main thread.

    Declaration

    Swift

    class func mainThread() -> NSThread

    Objective-C

    + (NSThread *)mainThread

    Return Value

    The NSThread object representing the main thread.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns whether the application is multithreaded.

    Declaration

    Swift

    class func isMultiThreaded() -> Bool

    Objective-C

    + (BOOL)isMultiThreaded

    Return Value

    YEStrue if the application is multithreaded, NOfalse otherwise.

    Discussion

    An application is considered multithreaded if a thread was ever detached from the main thread using either detachNewThreadSelector:toTarget:withObject: or start. If you detached a thread in your application using a non-Cocoa API, such as the POSIX or Multiprocessing Services APIs, this method could still return NOfalse. The detached thread does not have to be currently running for the application to be considered multithreaded—this method only indicates whether a single thread has been spawned.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the thread object representing the current thread of execution.

    Declaration

    Swift

    class func currentThread() -> NSThread

    Objective-C

    + (NSThread *)currentThread

    Return Value

    A thread object representing the current thread of execution.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an array containing the call stack return addresses.

    Declaration

    Swift

    class func callStackReturnAddresses() -> [AnyObject]

    Objective-C

    + (NSArray *)callStackReturnAddresses

    Return Value

    An array containing the call stack return addresses.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns an array containing the call stack symbols.

    Declaration

    Swift

    class func callStackSymbols() -> [AnyObject]

    Objective-C

    + (NSArray *)callStackSymbols

    Return Value

    An array containing the call stack symbols.

    Discussion

    This method returns an array of strings describing the call stack backtrace of the current thread at the moment this method was called. The format of each string is non-negotiable and is determined by the backtrace_symbols() API

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • The thread object's dictionary. (read-only)

    Declaration

    Swift

    var threadDictionary: NSMutableDictionary { get }

    Objective-C

    @property(readonly, retain) NSMutableDictionary *threadDictionary

    Discussion

    You can use the returned dictionary to store thread-specific data. The thread dictionary is not used during any manipulations of the NSThread object—it is simply a place where you can store any interesting data. For example, Foundation uses it to store the thread’s default NSConnection and NSAssertionHandler instances. You may define your own keys for the dictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • name name Property

    The name of the receiver.

    Declaration

    Swift

    var name: String!

    Objective-C

    @property(copy) NSString *name

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • stackSize stackSize Property

    The stack size of the receiver, in bytes.

    Declaration

    Swift

    var stackSize: Int

    Objective-C

    @property NSUInteger stackSize

    Discussion

    This value must be in bytes and a multiple of 4KB.

    To change the stack size, you must set this property before starting your thread. Setting the stack size after the thread has started changes the attribute size (which is reflected by the stackSize method), but it does not affect the actual number of pages set aside for the thread.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the current thread’s priority.

    Declaration

    Swift

    class func threadPriority() -> Double

    Objective-C

    + (double)threadPriority

    Return Value

    The current thread’s priority, which is specified by a floating point number from 0.0 to 1.0, where 1.0 is highest priority.

    Discussion

    The priorities in this range are mapped to the operating system's priority values. A “typical” thread priority might be 0.5, but because the priority is determined by the kernel, there is no guarantee what this value actually will be.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The receiver’s priority

    Declaration

    Swift

    var threadPriority: Double

    Objective-C

    @property double threadPriority

    Discussion

    The thread’s priority, which is specified by a floating point number from 0.0 to 1.0, where 1.0 is highest priority.

    The priorities in this range are mapped to the operating system's priority values. A “typical” thread priority might be 0.5, but because the priority is determined by the kernel, there is no guarantee what this value actually will be.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • Sets the current thread’s priority.

    Declaration

    Swift

    class func setThreadPriority(_ priority: Double) -> Bool

    Objective-C

    + (BOOL)setThreadPriority:(double)priority

    Parameters

    priority

    The new priority, specified with a floating point number from 0.0 to 1.0, where 1.0 is highest priority.

    Return Value

    YEStrue if the priority assignment succeeded, NOfalse otherwise.

    Discussion

    The priorities in this range are mapped to the operating system's priority values.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Not implemented.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • An NSThread object posts this notification when it receives the exit message, before the thread exits. Observer methods invoked to receive this notification execute in the exiting thread, before it exits.

    The notification object is the exiting NSThread object. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Posted when the first thread is detached from the current thread. The NSThread class posts this notification at most once—the first time a thread is detached using detachNewThreadSelector:toTarget:withObject: or the start method. Subsequent invocations of those methods do not post this notification. Observers of this notification have their notification method invoked in the main thread, not the new thread. The observer notification methods always execute before the new thread begins executing.

    This notification does not contain a notification object or a userInfo dictionary.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.