Release 1.0  Copyright ã1994 by Arcane Systems Ltd.  All Rights Reserved.

TKThread 

Inherits From:	TKObject

Declared In:	threadkit/TKThread.h

Class Description

The TKThread class provides an abstraction of a Mach thread.  It allows for an easy object-oriented approach to creating and managing threads in an application along with semantics for suspending threads at safe points.

Instance Variables

id theObject ;
SEL theSelector ;
cthread_t theCThread ;

theObject 	The object the new thread starts by messaging.

theSelector 	The message to send to theObject.

theCThread 	The Mach cthread implementing the instance.

Method Types

Spawning a thread	- init
- initFor:perform:

Accessing the mach thread	- thread
- cthread

Managing the current thread	+ currentThread
+ exit
+ sleep:
+ yield

Objective-C runtime safety	+ setRuntimePolicy:

Support for "dangerous actions"	+ startDangerousAction:
+ endDangerousAction

Class Methods

currentThread
+ currentThread

Returns the TKThread instance associated with the calling thread, or returns nil if the current thread was not created by a TKThread, as is the case with the main thread.

endDangerousAction
+ endDangerousAction

Unlocks the NXApp object and releases all threads put on hold by a previous startDangerousAction: message.

See also:  + startDangerousAction:

exit
+ exit

Stops the current thread and frees the associated TKThread, if there is one.

See also:  + yield

setRuntimePolicy:
+ setRuntimePolicy: (int) policy

Allows one of three policies regarding the objective-C runtime system:

TK_POLICY_DEFAULT	When this policy is in effect the ThreadKit automatically invokes objc_setMultithreaded() to make the system thread-safe when TKThread instances are active, and invokes it again to get maximum performance when no TKThread instances exist.  This is, as the name implies, the default policy.

TK_POLICY_NEVER	Setting this policy invokes objc_setMultithreaded() to turn off the thread-safe runtime system.  The objc_setMultithreaded() function is not called again unless the policy is changed.

TK_POLICY_ALWAYS	Setting this policy invokes objc_setMultithreaded() to turn on the thread-safe runtime system.  The objc_setMultithreaded() function is not called again unless the policy is changed.

sleep:
+ sleep: (int) msec

Designed as a thread-safe alternative to usleep().  Puts the calling thread to sleep for msec milliseconds.

startDangerousAction:
+ (BOOL) startDangerousAction: (int) msTimeout

This methods provides for the times an application needs to perform an action that is hazardous enough to require stopping all but one thread at safe locations.  Dynamically linking new classes into an application at runtime is a key example of a situation where this is necessary.

Sending a startDangerousAction: message to the TKThread class object will attempt to guarantee this situation.  It can only do so if all threads in the application have been created using instances TKThread or its subclasses.  If the situation cannot be arranged within msTimeout milliseconds, the method returns NO.

Otherwise the method pauses all threads but the current one, locks the AppKit in a usable state and returns YES.  Processing resumes as normal once an endDangerousAction message is received.  Calls to startDangerousAction: cannot be nested, a second startDangerousAction: will fail immediately and return NO.

Threads can only be paused safely if they invoke the yield or exit method before the timeout period expires.  Lengthy operations should periodically invoke the yield method for this reason.  If they fail to do so, the ThreadKit will be unable to initiate a "dangerous action" until they exit.

Note: To ensure that other threads find their way to a yield method in a timely fashion, the calling thread should not have any locks held, explicit or implicit when invoking this method.  For this reason you will rarely, if ever, be able to use startDangerousAction: from the main thread of your application since it always has the AppKit implicitly locked while in operation.  It is usually easiest to start a thread dedicated to the "dangerous action" in question:

- loadClasses: sender
{
	return [ [ TKThread alloc ] initFor: self perform: @selector ( loadClasses ) ] ;
}

- loadClasses
{
	if ( [ TKThread startDangerousAction: 1000 ] )
	{
		...
		
		[ TKThread endDangerousAction ] ;
	}
}

See also:  + endDangerousAction

yield
+ yield

Provides a hint to the scheduler that now would be a good time to execute another thread.  At the same time, it provides a hint to the ThreadKit that this is a safe time to suspend the current thread.  There are two situations under which this will happen:

·	Entering a dangerous code segment via startDangerousAction:
·	The TKThread object representing the thread is locked

If at all possible you should avoid holding any locks when the yield method is sent, since the thread may be suspended and unable to unlock the resources another thread needs.

See also:  + exit

Instance Methods

cthread
- (cthread_t) cthread

Returns the Mach cthread used to implement the TKThread.

See also:  - thread

init
- init

Since a TKThread instance cannot perform any work without a specified task, init simply frees the instance and returns nil.

initFor:perform:
- initFor: anObject perform: (SEL) aSelector

Starts a new thread and sends anObject the message specified by aSelector.

Note: Once the TKThread object is activated via this message it should be left alone.  It will free itself when the message is complete, and sending it further requests in the interim will have unpredictable results.

thread
- (thread_t) thread

Returns the Mach thread used to implement the TKThread.

See also:  - cthread