next up previous 264
Next: astTimeAdd - Add a time coordinate conversion to a TimeMap
Up: AST Function Descriptions
Previous: astText - Draw a text string for a Plot


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:
  • This function attempts to execute even if the global error status is set, but no further error report will be made if it subsequently fails under these circumstances.

  • This function is only available in the C interface.

  • This function always returns AST__RUNNING if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).
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.



next up previous 264
Next: astTimeAdd - Add a time coordinate conversion to a TimeMap
Up: AST Function Descriptions
Previous: astText - Draw a text string for a Plot

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council