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

TKObject 

Inherits From:	Object

Conforms To:	TKThreadLocking

Declared In:	threadkit/TKObject.h

Class Description

The TKObject class adds sophisticated lock management facilities to the basic Object class.  It combines the semantics of the MachKit's NXRecursiveLock and NXConditionLock classes and adds support for non-blocking lock attempts.  While the interface presented by TKObject instances is identical to that added to Object by the Object ( TKThreadLocking ) category, the implementation TKObject uses to overrides it with is much more efficient.

Instance Variables

mutex_t threadLock ;
condition_t threadCondition ;
thread_t lockingThread ;
int lockCount ;
int unlockState ;

threadLock 	A Mach mutex protecting the rest of the object's state

threadCondition 	A Mach condition signalling changes to the TKObject's unlockState

lockingThread 	The thread identifier for the thread currently holding a lock

lockCount 	The number of locks held by the locking thread

unlockState 	The state specified by the last thread to completely unlock the TKObject

Method Types

Creating and freeing a TKObject	- init
- free

ThreadKit lock identification	- threadKitLockObject

Locking the object	- threadLock
- threadLockWhen:
- threadUnlock
- threadUnlockWith:
	- tryThreadLock
- tryThreadLockFor:

Instance Methods

free
- free

Deallocates threadLock and threadCondition before freeing the instance.

init
- init

Allocates the threadLock and threadCondition once the object is initialized, and unlocks the object with an unlockState of zero.

threadKitLockObject
- threadKitLockObject

Returns self.

threadLock
- threadLock

If the object is already locked by the calling thread, the lock count is incremented by one.  Otherwise, this method waits until no other thread holds a lock on the object.  The object is then locked, setting the lock count to one.  As a result only one thread may lock an object at any given time and paired sets of lock / unlock operations may be nested as deeply as desired.  Returns self once the lock has been aquired.

threadLockWhen:
- threadLockWhen: (int) state

Behaves in the same manner as threadLock except that it will not lock an unlocked object whose state is not equal to state.  It will wait while object is locked and unlocked by other threads until it is unlocked with the proper state.  Returns self once the lock has been aquired.

state should normally be a positive integer value. Calling this method with the constant TK_ANY_STATE is equivelant to calling threadLock.

threadUnlock
- threadUnlock

Returns nil if the calling thread doesn't currently hold a lock on the object.  Otherwise reduces the internal lock count by one and returns self.  Once the lock count reaches zero, the object is unlocked and its state is set to zero.

threadUnlockWith:
- threadUnlockWith: (int) state

Behaves in the same manner as threadUnlock except that when the lock count reaches zero, the object is unlocked and its state is set to state.

tryThreadLock
- (BOOL) tryThreadLock

Behaves in the same manner as threadLock except that it always returns immediately.  Since a lock is not always available immediately, the method returns YES if the lock was successfully aquired, and NO otherwise.

state should normally be a positive integer value.  Calling this method with the constant TK_DEFAULT_STATE is equivelant to calling threadUnlock.

tryThreadLockFor:
- tryThreadLockFor: (int) state

Behaves in the same manner as threadLockWhen: except that it always returns immediately.  Since a lock is not always available immediately, the method returns YES if the lock was successfully aquired, and NO otherwise.

state should normally be a positive integer value.  Calling this method with the constant TK_ANY_STATE is equivelant to calling tryThreadLock.  Calling this method with the constant TK_RECURSIVE_STATE will succeed only if the thread already has a valid lock.