astAnnulastAnnul - Annul a pointer to an Object

Description:
This function annuls a pointer to an ObjectObject so that it is no longer recognised as a valid pointer by the AST library. Any resources associated with the pointer are released and made available for re-use.

This function also decrements the Object's RefCountRefCount attribute by one. If this attribute reaches zero (which happens when the last pointer to the Object is annulled), then the Object is deleted.

Synopsis:
AstObject $*$astAnnul( AstObject $*$this )
Parameters:
this
The Object pointer to be annulled.
Class Applicability:
Object
This function applies to all Objects.
Returned Value:
astAnnul()
A null Object pointer (AST__NULL) is always returned.
Notes:
  • This function will attempt to annul the pointer even if the Object is not currently locked by the calling thread (see astLockastLock).

  • This function attempts to execute even if the AST error status is set on entry, although no further error report will be made if it subsequently fails under these circumstances. In particular, it will fail if the pointer suppled is not valid, but this will only be reported if the error status is clear on entry.