ACQUIRE MUTEX Command

Description:

This command acquires exclusive access to a shared resource, known as a mutex. The mutex is identified by its name and scope (which must be either "LOCAL" or "TEST-WIDE"). A test-wide mutex is one that is shared by all scripts running as part of a distributed test; a local mutex is only shared between scripts running on the local node.

By default, if an attempt is made to acquire a mutex that has already been acquired by another script (within the same scope), then the thread will be suspended until the mutex is released. However, if a time-out period is specified, this represents the maximum number of seconds that OpenSTA will wait for the mutex to be released before timing out the request. A period of zero indicates that the request should be timed out immediately if the mutex has been acquired by another script.

The "ON TIMEOUT GOTO tmo_label" clause can be specified to define a label to which control should be transferred if the request times out. In addition, the "ON ERROR GOTO err_label" clause can be specified to define a label to which control should be transferred in the event of an error, or if the request times out and there was no "ON TIMEOUT GOTO tmo_label" clause.

Format:

 ACQUIRE {scope} MUTEX mutex_name {&}
 	 {,WITH TIMEOUT period {,ON TIMEOUT GOTO tmo_label}} {&}
 	 {,ON ERROR GOTO err_label}

Parameters:

scope

The scope of the mutex to be acquired. This must be either "LOCAL" or "TEST-WIDE", and defaults to "LOCAL".

mutex-name

A character variable, or quoted character string, containing the name of the mutex which is to be acquired. "mutex-name" must be a valid OpenSTA Dataname.

period

An integer variable or value, defining the number of seconds to wait before an unsatisfied request is timed out. The valid range is 0-2147483647.

tmo_label

A label defined within the current scope of the script, to which control branches if a time-out occurs.

err_label

A label defined within the current scope of the script, to which control branches if an error occurs, or the command times out and "tmo_label" is not specified.

Example:

 ACQUIRE LOCAL MUTEX "MUMPS-SERVER", ON ERROR GOTO mumps-error

See also:

Synchronization Commands