PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSThread


Inherits from:
NSObject
Conforms to:
NSObject
(NSObject)
Declared in:
Foundation/NSThread.h




Class Description


An NSThread object controls a thread of execution. Use NSThread when you want to have an Objective-C method run in its own thread of execution or if you need to terminate or delay the current thread.

A thread is an executable unit. A task is made up of one or more threads. Each thread has its own execution stack and is capable of independent input/output. All threads share the virtual memory address space and communication rights of their task. When a thread is started, it is detached from its initiating thread. The new thread runs independently. That is, the initiating thread does not know the new thread's state.

To have an Objective-C message run in its own thread of execution, send the message detachNewThreadSelector:toTarget:withObject: to the NSThread class object. This method detaches a new thread from the current thread, and the specified target executes the specified method in that thread. When the target has finished executing the method, the thread exits.

When you use detachNewThreadSelector:toTarget:withObject:, your application becomes multithreaded. At any time you can send isMultiThreaded to find out if the application is multithreaded, that is, if a thread was ever detached from the main thread. isMultiThreaded returns YES even if the detached thread has completed execution.


Note: Do not interchange the use of the cthreads functions and NSThread objects within an application. In particular, do not use cthread_fork() to create a thread that executes an Objective-C message. isMultiThreaded returns YES only if detachNewThreadSelector:toTarget:withObject: was used to create the thread.

If you need to terminate the current thread, send the exit message to the NSThread class object. Similarly, you send the sleepUntilDate: message to the NSThread class object to block the current thread for a period of time.




Method Types


Querying an NSThread
+ isMultiThreaded
+ currentThread
- threadDictionary
Detaching a thread
+ detachNewThreadSelector:toTarget:withObject:
Stopping the Current Thread
+ sleepUntilDate:
+ exit


Class Methods



currentThread

+ (NSThread *)currentThread

Returns an object representing the current thread of execution.

See Also: + detachNewThreadSelector:toTarget:withObject:



detachNewThreadSelector:toTarget:withObject:

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

Detaches a new thread for the message aSelector sent to aTarget with the single argument anArgument. The method aSelector must take only one argument and must not have a return value. The method aSelector is responsible for setting up an autorelease pool for the newly detached thread, and freeing that pool before it exits. 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 is the first thread detached from the current thread, this method posts the NSWillBecomeMultiThreadedNotification with object nil to the default notification center.

See Also: + currentThread, + isMultiThreaded



exit

+ (void)exit

Terminates the current thread, using the currentThread class method to access that 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.

See Also: + currentThread, + sleepUntilDate:



isMultiThreaded

+ (BOOL)isMultiThreaded

Returns YES if the application is multithreaded. An application is considered multithreaded if a thread was ever detached from the main thread using detachNewThreadSelector:toTarget:withObject:. If you detached a thread using the cthread_fork() function, this method could still return NO. The detached thread does not have to be running for an application to be considered multithreaded-it may have already exited.

sleepUntilDate:

+ (void)sleepUntilDate:(NSDate *)aDate

Blocks the current thread until the time specified by aDate. No run loop processing occurs while the thread is blocked.

See Also: + currentThread, + exit




Instance Methods



threadDictionary

- (NSMutableDictionary *)threadDictionary

Returns the NSThread's dictionary, to which you can add data specific to the receiving NSThread. The thread dictionary is not used during any manipulations of the NSThread-it is simply a place where you can store any interesting attributes of a thread. For example, Foundation uses it to store the thread's NSRunLoop and NSAssertionHandler instances. You may define your own keys for the dictionary. Accessing the thread dictionary may be slower than it usually is to access an NSMutableDictionary.


Notifications


NSDidBecomeSingleThreadedNotification

Description forthcoming.

NSThreadWillExitNotification

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

This notification contains a notification object but no userInfo dictionary. The notification object is the exiting NSThread.

NSWillBecomeMultiThreadedNotification

Posted when the first thread is detached from the current thread. NSThread posts this notification at most once-the first time a thread is detached using detachNewThreadSelector:toTarget:withObject:. Any subsequent invocations of detachNewThreadSelector:toTarget:withObject: do not post this notification. The observer methods invoked to receive this notification execute in the main thread, not the new thread, and they execute before the new thread begins executing.

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



Table of Contents