Create Pointer-Based Mutex (CRTMTX)

Instruction Syntax

Op Code (Hex)	Operand 1	Operand 2	Operand 3
03C3	Mutex	Creation template	Result

Operand 1: Space pointer.

Operand 2: Space pointer.

Operand 3: Signed binary(4) variable scalar.

Bound Program Access
`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:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Mutex control area	Char(16)
16	10	Optional name string	Char(16)
32	20	--- End ---

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:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Reserved (binary 0)	Char(1)
1	1	Name option Hex 00 = No name string is associated with this mutex (this is the default option when the template is not supplied). Hex 01 = Mutex has a name string associated with it. Name string immediately follows the mutex in the template.	Char(1)
2	2	Keep valid option Hex 00 = Mutex will be destroyed when its owning thread is terminated (this is the default option when the template is not supplied). Hex 01 = Mutex will remain valid when its owning thread is terminated. The mutex will be marked as being in a pending state.	Char(1)
3	3	Recursive option Hex 00 = Recursive attempts to lock this mutex will not be permitted (this is the default option when the template is not supplied). Hex 01 = Recursive attempts to lock this mutex will be permitted by the same thread that has already locked the mutex.	Char(1)
4	4	Reserved (binary 0)	Char(28)
32	20	--- End ---

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:

EINVAL: 3021 - The value specified for the argument is not correct.

ENOMEM: 3460 - Storage allocation request failed.

EPERM: 3027 - Operation not permitted.

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