ACQUIRE MUTEX Command

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 timeout 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.

Command Definition:

ACQUIRE {scope} MUTEX mutex-name
	{,WITH TIMEOUT period {,ON TIMEOUT GOTO tmo-label}}
	{,ON ERROR GOTO err-label}

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 timeout occurs.

err-label

A label defined within the current scope of the Script to which control branches if an error occurs.

Example:

ACQUIRE LOCAL MUTEX "USERMUT", ON ERROR GOTO USERMUT_ERR