astThread

Determine the thread that owns an Object

Description:

Returns an integer that indicates whether the supplied Object (or Object pointer) is currently unlocked, or is currently locked by the running thread, or another thread.

Synopsis

int astThread( AstObject this, int ptr )

Parameters:

this
Pointer to the Object to be checked.
ptr
If non-zero, returns information about the supplied Object pointer, rather than the Object structure itself. See " Object Pointers and Structures" below.

Returned Value

astThread()
A value of AST__UNLOCKED is returned if the Object (or pointer) is currently unlocked (i.e. has been unlocked using astUnlock but has not yet been locked using astLock). A value of AST__RUNNING is returned if the Object (or pointer) is currently locked by the running thread. A value of AST__OTHER is returned if the Object (or pointer) is currently locked by the another thread.

Notes:

Object Pointers and Structures

At any one time, an AST Object can have several distinct pointers, any one of which can be used to access the Object structure. For instance, the astClone function will produce a new distinct pointer for a given Object. In fact, an AST " pointer" is not a real pointer at all - it is an identifier for a " handle" structure, encoded to make it look like a pointer. Each handle contains (amongst othere things) a " real" pointer to the Object structure. This allows more than one handle to refer to the same Object structure. So when you call astClone (for instance) you get back an identifier for a new handle that refers to the same Object as the supplied handle.

In order to use an Object for anything useful, it must be locked for use by the running thread (either implicitly at creation or explicitly using astLock). The identity of the thread is stored in both the Object structure, and in the handle that was passed to astLock (or returned by the constructor function). Thus it is possible for a thread to have active pointers for Objects that are currently locked by another thread. In general, if such a pointer is passed to an AST function an error will be reported indicating that the Object is currently locked by another thread. The two exceptions to this is that astAnnul can be used to annull such a pointer, and this function can be used to return information about the pointer.

The other practical consequence of this is that when astEnd is called, all active pointers currently owned by the running thread (at the current context level) are annulled. This includes pointers for Objects that are currently locked by other threads.

If the " ptr" parameter is zero, then the returned value describes the Object structure itself. If " ptr" is non-zero, then the returned value describes the supplied Object pointer (i.e. handle), rather than the Object structure.