Lock Pointer-Based Mutex (LOCKMTX)

Operand 2: Space pointer.

Operand 3: Signed binary(4) variable scalar.

Built-in number for LOCKMTX is 157.
LOCKMTX (
         mutex                   : address
         lock_request_template   : address
) :   signed binary(4)   /* result */

Note: The term "mutex" in this instruction refers to a "pointer-based mutex".

Description

The mutex, whose address is contained in operand 1, is allocated exclusively to the issuing thread. Mutual exclusion is achieved between the thread with the allocated mutex lock and all other threads attempting to acquire the same mutex lock. If the mutex lock is successful, LOCKMTX returns with the issuing thread as its holder.

The mutex must have been previously created by the CRTMTX instruction or be a copy of a mutex that was previously created by the CRTMTX instruction prior to attempting to lock the mutex. See the CRTMTX instruction for additional information regarding mutex copies.

The lock request template whose address is passed in operand 2 is used to determine if and for how long the issuer will wait for the mutex to become available in the event the mutex is already locked. The lock options are used to place the issuer into the mutex wait state. If an invalid option is specified, an EINVAL error number is returned. If operand 2 in a bound program is a null pointer value, the default lock request template is used (the binary 0 value is the default action). Operand 2 in non-bound programs must be a pointer to a lock request template. The pointer does not exist  (hex 2401) exception is signaled if a null pointer value is used for operand 2 in a non-bound program. If the mutex lock can be immediately allocated to the issuer, then the lock request template is ignored.

Result is used to indicate the success or failure of the LOCKMTX instruction. If the mutex is locked by this instruction, then result is set to 0. If an error occurs, then the result is set to an error condition.

Mutexes can have either non-recursive or recursive behavior, which is specified at the time of creation. See the CRTMTX instruction for more information on mutex creation. A non-recursive mutex can only be locked once by a thread. Additional attempts to lock the same non-recursive mutex by a thread, will cause the EDEADLK error number to be returned. If a mutex was created as a recursive mutex then LOCKMTX can be used to recursively lock the mutex. The machine keeps track of the number of recursive locks for the mutex and requires that the thread use the Unlock Pointer-Based Mutex (UNLKMTX) instruction the same number of times to unlock the mutex before the mutex can be locked by a different thread. The maximum number of recursive locks is 32,767. The ERECURSE error number is returned if the maximum number of recursive locks is exceeded.

The mutex must be aligned on a 16-byte boundary.

The format of the lock request template follows:

The time-out option describes the action taken when LOCKMTX cannot allocate the mutex to the issuer immediately.

All other values for time-out option are reserved.

The lock options describes the action taken when LOCKMTX causes the issuer to be put into a mutex wait state.

The wait time-out format option determines the format of the wait time-out value. If the wait time-out format is specified as 0, then the wait time-out value consists of two 4-byte fields, specifying the number of seconds and the number of microseconds to wait for the mutex if it cannot be locked immediately. If the wait time-out format is specified as 1, then the wait time-out value consists of a single 8-byte field. See Standard Time Format for additional information on the format of the wait time-out value if wait time-out format is specified as 1. This field is only applicable if the time-out option is set to hex 01. If the time-out option is not set to hex 01, this field is ignored.

The MPL control during wait option controls whether the thread is removed from the current MPL (multiprogramming level) set or remains in the current MPL set when the thread enters a mutex wait. When entering a mutex wait state, the thread will normally remain in the current MPL set for an implementation-defined period which will not exceed 2 seconds. If the mutex wait has not been satisfied by the end of this period, the thread is automatically removed from the current MPL set. The automatic removal does not change or affect the total wait time specified on the LOCKMTX instruction. If the MPL control during wait option specifies do not remain in current MPL set (value of 1), then the thread will leave the MPL set immediately.

The asynchronous signals processing option controls the action to be taken if an asynchronous signal is pending or received while in a mutex wait. If an asynchronous signal that is not blocked or ignored is generated for the thread and the asynchronous signals processing option indicates allow asynchronous signal processing during mutex wait, the mutex wait is terminated and the result set to EINTR. Otherwise, when the asynchronous signals processing option indicates do not allow asynchronous signal processing during mutex wait, the thread remains in the wait until the mutex is allocated exclusively to the thread or until the wait time-out value expires.

The wait type option is used by kernel-mode programs or procedures to specify what type of wait to perform. The wait type field is ignored when the thread execution mode is not kernel-mode.

The wait time-out value establishes the maximum amount of time that the issuer waits for the requested mutex when the mutex lock cannot be immediately obtained and the time-out option is set to wait for a specified period of time (hex 01). The format of this field differs depending on which value is specified by the wait time-out format. If the wait time-out format is 0, then the wait time-out value consists of two 4-byte values, specifying the number of seconds and the number of microseconds to wait for the mutex. If the wait time-out format is 1, then the wait time-out value is a 64-bit unsigned binary value.> See Standard Time Format for additional information on the format of the wait time-out value if wait time-out format is specified as 1. If the wait time-out value is binary 0, then the process default wait time-out value is used. This field is only applicable if the time-out option is set to hex 01. If the time-out option is not set to hex 01, this field is ignored.

If a mutex is destroyed while another thread has a pending request to lock the mutex, an EDESTROYED error number is returned to the waiting thread. The ETYPE error number is returned if the mutex operand references a synchronization object that is not a pointer-based mutex.

The keep valid option on the Create Mutex (CRTMTX) instruction specifies whether the mutex is to remain valid when a thread is terminated while holding the lock on the mutex. The keep valid option must be set to hex 01 if a mutex should be remain valid after thread termination. The mutex is considered to be in a pending state when it is kept valid after thread termination. The next thread to lock a pending mutex will revalidate the mutex, but will receive an EUNKNOWN error number to indicate that the resource protected by this mutex may need special handling. Appropriate action is left up to the MI user's discretion. Specifying hex 00 for the keep valid option will result in the locked mutex being destroyed during thread termination. Threads waiting on the destroyed mutex will receive an EOWNERTERM error number.

If the space where a mutex resides is destroyed or corrupted, the system may detect this condition and attempt to clean up the mutex resource. This cleanup action will cause any thread waiting on the mutex to awaken with a return value of EINVAL.

Authorization Required

• None

Lock Enforcement

• None

Error conditions

The result is set to one of the following:

Exceptions

06 Addressing

• 0601 Space Addressing Violation
• 0602 Boundary Alignment
• 0603 Range

08 Argument/Parameter

• 0801 Parameter Reference Violation

10 Damage Encountered

• 1004 System Object Damage State
• 1044 Partial System Object Damage

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2202 Object Destroyed
• 2203 Object Suspended
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

36 Space Management

• 3601 Space Extension/Truncation

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed