#### Description:

The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an Object that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using astUnlock) and the new thread must then lock it (using astLock) before the new thread can use the Object.

The `"` wait`"` parameter determines what happens if the supplied Object is curently locked by another thread when this function is invoked.

#### Synopsis

void astLock( AstObject ∗this, int wait )

#### Parameters:

##### this

Pointer to the Object to be locked.

##### wait

If the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for `"` wait`"` , the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object.

#### Applicability

##### Object

This function applies to all Objects.

#### Notes:

- The astAnnul function is exceptional in that it can be used on pointers for Objects that are not currently locked by the calling thread. All other AST functions will report an error.

- The Locked object will belong to the current AST context.

- This function returns without action if the Object is already locked by the calling thread.

- If simultaneous use of the same object is required by two or more threads, astCopy should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy).

- This function is only available in the C interface.

- This function returns without action 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).

Copyright (C) 2021 East Asian Observatory