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

TKApplication 

Inherits From:	Application : Responder : Object

Conforms To:	TKThreadLocking

Declared In:	threadkit/TKApplication.h

Class Description

The TKApplication class serves two purposes:

Firstly, to provide a mechanism for initializing the ThreadKit itself.  In order for this to occur, every application based on the ThreadKit must use an instance of TKApplication or a subclass thereof instead of the AppKit's Application class.

Secondly, to extend the locking semantics of the ThreadKit to the Application Kit as a whole.  This is done in order for multi-threaded applications to be able to work with Application Kit classes.  Since a pointer the single instance of TKApplication is available in the global variable NXApp, code in any method of any class can quickly and easily send messages to the TKApplication instance in order to lock or unlock the Application Kit.

While TKApplication conforms to the TKThreadLocking protocol, the methods threadLockWhen:, tryThreadLock, tryThreadLockFor: and threadUnlockWith: always fail.  See the description of the individual methods for the reasons why.

Instance Variables

void * hiddenContents [ ];

hiddenContents 	The implementation of TKApplication is private.

Method Types

Initializing the ThreadKit	- threadKitSetup
- threadKitCleanup

ThreadKit lock identification	- threadKitLockObject

Explicit AppKit Locking	- threadLock
- threadLockWhen:
- threadUnlock
- threadUnlockWith:
	- tryThreadLock
- tryThreadLockFor:

Instance Methods

threadKitCleanup
- threadKitCleanup

Automatically invoked just before the TKApplication instance is freed, this method allows the ThreadKit to clean up where necessary.

threadKitLockObject
- threadKitLockObject

Returns self.

threadKitSetup
- threadKitSetup

Automatically invoked just after the TKApplication instance is created, this method allows the ThreadKit to initialize itself as necessary.

threadLock
- threadLock

If the AppKit is already locked by the calling thread, the lock count is incremented by one.  Otherwise, this method waits until no other thread holds an explicit lock on the object.  The main thread is then asked to release its implicit lock and the AppKit is finally locked, setting the lock count to one.  As a result only one thread may lock the AppKit 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.

Once the AppKit is locked, it is placed in a condition that guarantees the locking thread safe access to any and all AppKit methods and classes.  Operations on AppKit objects within threads can thus be bracketed by threadLock and threadUnlock messages:

[ NXApp threadLock ] ;

...

[ NXApp threadUnlock ] ;

Note that when no thread has an explicit lock on the AppKit, the application's main thread has an implicit lock, allowing it to use AppKit resources with invoking the locking mechansim while still remaining thread-safe.  In order to avoid trying to gain an explicit lock when it already has an implicit lock, threadLock returns nil if called from the application's main thread.

threadLockWhen:
- threadLockWhen: (int) state

Returns nil since the TKApplication instance manages its own state which should not be interfered with.

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 AppKit is released and implicitly relocked by the main thread.

threadUnlockWith:
- threadUnlockWith: (int) state

Returns nil since the TKApplication instance manages its own state which should not be interfered with.

tryThreadLock
- (BOOL) tryThreadLock

Returns NO since the AppKit is always either explicitly or implicitly locked.

tryThreadLockFor:
- tryThreadLockFor: (int) state

Returns NO since the AppKit is always either explicitly or implicitly locked.