Create Pointer-Based Mutex (CRTMTX)

Operand 2: Space pointer.

Operand 3: Signed binary(4) variable scalar.

Built-in number for CRTMTX is 161.
CRTMTX (
        mutex               : address
        creation_template   : address
) :   signed binary(4)  /* result */

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

Description

A mutex is created and associated with the storage location of the mutex whose address is passed in operand 1. The mutex is initialized into the unlocked state so it may be used for mutual exclusion between threads attempting to lock the mutex. An optional name string can be associated with the mutex. A mutex must be created before it can be used for synchronization with the Lock Pointer-Based Mutex (LOCKMTX) and Unlock Pointer-Based Mutex (UNLKMTX) instructions, and with other mutex instructions such as Destroy Pointer-Based Mutex (DESMTX) and Materialize Mutex (MATMTX).

Result is used to indicate the success or failure of the CRTMTX instruction. Following a successful CRTMTX, the mutex is used by passing its address as a parameter to other mutex instructions.

Mutexes are temporary entities that do not persist beyond the current IPL in which they are created. Following a subsequent IPL, mutexes must be re-created before they can be used. Similarly, mutexes created in an independent ASP do not persist beyond the current vary on of the independent ASP in which they are created. Following a subsequent vary on, mutexes must be re-created before they can be used. Mutexes can be explicitly destroyed prior to a subsequent IPL or independent ASP vary off/vary on cycle by using the DESMTX instruction.

It is important to destroy mutexes when they are no longer needed. When a mutex is created, system resources are allocated for the mutex. These resources remain allocated until the mutex is destroyed (see DESMTX instruction) or the system is IPLed, thereby leaving fewer mutex resources available in the system for other threads to use. In addition, performance degradation can occur as unused mutexes accumulate on the system and are not destroyed.

The mutex must be aligned on a 16-byte boundary. The format is as follows:

The mutex control area contains a synchronization pointer. This field is initialized by the CRTMTX instruction, and is used only by the machine. The caller of CRTMTX should simply define the mutex control area as a 16-byte character field.

The mutex must be at least 16 bytes in length. If the mutex creation template associates a name with the mutex, then the optional name string must reside in the storage immediately following the 16-byte mutex control area and be initialized prior to the CRTMTX call. The optional name string is a character string which can be a maximum of 16 bytes long. The name string must either be null-terminated (up to 15 bytes of data followed by a null byte), or it must be 16 bytes long, padded with blanks. If a null byte is found within the first 16 bytes of the name string, the name string is considered to be null-terminated. No validity checking is performed to ensure mutex names are unique in the system, and it is possible to have multiple mutexes with the same name; however, it is recommended that each mutex be given a unique name. This name cannot be used on any mutex instructions to identify the mutex; rather, it is used mainly to be able to identify the mutex more easily during problem determination. The mutex name, if specified, is returned from the MATMTX instruction.

The creation template specified by operand 2 is used to initialize the mutex. The format is as follows:

The name option field specifies whether the mutex is to be named. The name option field must be set to hex 01 in order to associate a name with the mutex. Setting the name option to hex 00 will create a mutex without a name. All other values for name option are reserved.

Keep valid option field specifies whether the mutex is to remain valid when a thread is terminated while holding the lock on the mutex. The keep valid option field must be set to hex 01 to indicate that the mutex should 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 require special handling. Appropriate action is left up to the MI user's discretion. Specifying hex 00 for the keep valid option field will result in the mutex being destroyed during thread termination. Threads waiting for the mutex that was locked by the terminating thread will be returned the EOWNERTERM error number.

The recursive option field specifies whether recursive locking of the mutex will be allowed. See LOCKMTX for additional information on the recursive behavior of a pointer-based mutex.

If operand 2 in a bound program is a null pointer value, the mutex will be created with the default initialization options. Operand 2 in non-bound programs must be a pointer to a creation template. The pointer does not exist  (hex 2401) exception will be signaled if a null pointer value is used for operand 2 in a non-bound program.

If the mutex is created by this instruction, then result is set to 0. If an error occurs, then the result is set to an error number. The EINVAL error number will be returned if an invalid parameter is specified. The EPERM error number is returned when the address passed in operand 1 is in teraspace and the issuing thread does not have teraspace write permissions to that address. The ENOMEM error number is returned when no more mutexes can be created due to lack of system resources.

An attempt to create a new mutex using the same space as an existing mutex will cause the existing mutex to be destroyed. An attempt to create a new mutex using the same space as a copy of an existing mutex will not destroy the existing mutex; instead, a new mutex will be created in the space where the copy resides.

Programming Considerations

Although copies of an existing mutex can be made by other instructions that copy memory and preserve pointers, or can effectively be made by teraspace memory mapping techniques, making and using mutex copies is not recommended. Some restrictions may apply to mutex copies in other releases.

Authorization Required

• None

Lock Enforcement

• None

Error conditions

The result will be 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