Materialize Mutex (MATMTX)

Instruction Syntax

Bound Program Access 
Built-in number for MATMTX is 163.
MATMTX (
        receiver   : address
        mutex      : address
        options    : address of unsigned binary(4) value OR
                     null pointer value
)
Note: The term mutex in this instruction refers to a pointer-based mutex.

Description:

The current state of the mutex or replica of a mutex whose address is passed in the mutex operand is materialized into the receiver space identified by the receiver operand with the information returned specified by the options operand. A replica of a mutex can be returned by the MATPRMTX instruction. If the instruction completes unsuccessfully, an exception is generated.

The receiver operand specifies a space containing the materialization template that is to receive the information returned. The space must be aligned on a 16-byte boundary. If not, the boundary alignment (hex 0602) exception is generated.

The mutex operand specifies a space containing the mutex to be materialized. The space must be aligned on a 16-byte boundary. If not, the boundary alignment (hex 0602) exception is generated. An invalid mutex (hex 3804) exception is generated if an attempt is made to materialize a mutex that does not exist.

The options operand specifies a space containing a 4-byte binary field that is used to indicate the type of information that should be returned by this instruction. The materialization options referenced by the options operand has the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Reserved (binary 0) Bits 0-28
0
0
Mutex attributes format option
0 =
Return additional attributes in template format 0
1 =
Return additional attributes in template format 1
Bit 29
0
0
Mutex attributes option
0 =
Do not return additional mutex attributes
1 =
Return additional mutex attributes
Bit 30
0 0 Reserved (binary 0) Bit 31
4
4
--- End ---
 

The mutex attributes format option field is used to select the template format in which additional mutex attributes are to be returned. If mutex attributes option is set to return additional mutex attributes, then mutex attributes format option may be set to return additional attributes in template format 0 or return additional attributes in template format 1. If mutex attributes option is set to do not return additional mutex attributes, then this field is ignored.

The mutex attributes option field is used to select whether or not additional mutex attributes are to be returned. If mutex attributes option is set to do not return additional mutex attributes, then a standard materialization template is used. If mutex attributes option is set to return additional mutex attributes, then a materialization template with extended mutex descriptors is used.

If the options operand contains a null pointer value, the default materialization options are used. All values other than those specifically defined for materialization options are reserved and will cause a scalar value invalid (hex 3203) exception to be generated. The format of the information returned in the materialization template is different, depending on the materialization options selected.

The materialization template has the following standard format when mutex attributes option is set to do not return additional mutex attributes:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization size specification Char(8)
0 0
  • Number of bytes provided for materialization
  • Bin(4)
4 4
  • Number of bytes available for materialization
  • Bin(4)
8 8 Reserved (binary 0) Char(4)
12 C Number of waiters Bin(4)
16 10 Mutex name Char(16)
32 20 Mutex owner process ID Char(30)
62 3E Reserved (binary 0) Char(18)
80 50 Wait list descriptors (repeated for each thread waiting for mutex) [*] Char(48)
80 50
  • Waiter process ID
  • Char(30)
110 6E
  • Reserved (binary 0)
  • Char(18)
*
*
--- End ---
 

The first 4 bytes of the materialization template identifies the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length invalid (hex 3803) exception to be signaled.

The second 4 bytes of the materialization template identifies the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver that can be used to completely fill wait list descriptors. Partial descriptors are not returned. If the number of bytes provided would cause the storage boundary of the space provided for the receiver to be exceeded, and if the number of bytes available would actually exceed this boundary, then a space addressing violation (hex 0601) exception is signaled. If the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length invalid (hex 3803) exception described previously.

The number of waiters is the number of threads that are currently waiting for the mutex to become unlocked.

Mutex name contains the name of the mutex. The name is left-justified and padded to the right with blanks. If the mutex was created using a null-terminated name string, the name materialized with this instruction is null-terminated instead of padded with blanks. If the mutex was created without a name, this field will contain the character string "UNNAMED_" followed by the first 8 characters of the program which created the mutex.

The mutex owner process ID contains the name of the process containing the thread that holds the mutex lock. The name returned here is the 30-character process control space (PCS) name. If this field is all blanks, the mutex is not locked or the thread that held the mutex lock has ended.

The wait list descriptors identify the threads waiting for the mutex to become unlocked. The waiter process ID contains the name of the process containing the waiting thread. The name returned here is the 30-character PCS name. If this field is all blanks, the thread waiting on the mutex has ended.

The materialization template has the following extended format when mutex attributes option is set to return additional mutex attributes and mutex attributes format option is set to return additional attributes in template format 0:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization size specification Char(8)
0 0
  • Number of bytes provided for materialization
  • Bin(4)
4 4
  • Number of bytes available for materialization
  • Bin(4)
8 8 Reserved (binary 0) Char(4)
12 C Number of waiters Bin(4)
16 10 Mutex name Char(16)
32 20 Mutex owner process ID Char(30)
62 3E Reserved (binary 0) Char(2)
64 40 Mutex owner thread ID Char(8)
72 48 Mutex owner unique thread value Char(8)
80 50 Wait list descriptors (repeated for each thread waiting for mutex) [*] Char(48)
80 50
  • Waiter process ID
  • Char(30)
110 6E
  • Reserved (binary 0)
  • Char(2)
112 70
  • Waiter thread ID
  • Char(8)
120 78
  • Waiter unique thread value
  • Char(8)
*
*
--- End ---
 

The contents of the template fields are as defined for the previous template(s), unless specifically defined or redefined as follows:

The mutex owner process ID contains the name of the process containing the thread that holds the mutex lock. The name returned here is the 30-character PCS name. The mutex owner thread ID contains a process specific value that identifies the thread within the process that holds the mutex lock. If mutex owner process ID is all blanks and mutex owner thread ID is binary 0, the mutex is not locked or the thread that held the mutex lock has ended. The mutex owner unique thread value contains a system-wide unique value that identifies the specific thread that holds the mutex lock. If this field is binary 0, the mutex is not locked. This field cannot be used as input on any other MI instruction, but may be useful for debug purposes.

The wait list descriptors identify the threads waiting for the mutex to become unlocked. The waiter process ID contains the name of the process containing the waiting thread. The name returned here is the 30-character PCS name. The waiter thread ID contains a process specific value that identifies the thread within the process that is waiting for the mutex. If waiter process ID is all blanks and waiter thread ID is binary 0, the waiting thread has ended. The waiter unique thread value contains a system-wide unique value that identifies the specific thread that is waiting for the mutex. This field cannot be used as input on any other MI instruction, but may be useful for debug purposes.

The materialization template has the following extended format when mutex attributes option is set to return additional mutex attributes and mutex attributes format option is set to return additional attributes in template format 1.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization size specification Char(8)
0 0
  • Number of bytes provided for materialization
  • Bin(4)
4 4
  • Number of bytes available for materialization
  • Bin(4)
8 8 Reserved (binary 0) Char(4)
12 C Number of waiters Bin(4)
16 10 Mutex name Char(16)
32 20 Mutex owner process ID Char(30)
62 3E Reserved (binary 0) Char(2)
64 40 Mutex owner thread ID Char(8)
72 48 Mutex owner unique thread value Char(8)
80 50 Last locker process ID Char(30)
110 6E Reserved (binary 0) Char(2)
112 70 Last locker thread ID Char(8)
120 78 Last locker unique thread value Char(8)
128 80 Last unlocker process ID Char(30)
158 9E Reserved (binary 0) Char(2)
160 A0 Last unlocker thread ID Char(8)
168 A8 Last unlocker unique thread value Char(8)
176
B0
Recursive flag
Hex 00 =
Recursive attempts to lock this mutex will not be permitted
Hex 01 =
Recursive attempts to lock this mutex will be permitted by the same thread that has already locked the mutex.
Char(1)
177
B1
Keep valid flag
Hex 00 =
Mutex will be destroyed when its owning thread is terminated
Hex 01 =
Mutex will remain valid when its owning thread is terminated
Char(1)
178
B2
Pending state flag
Hex 00 =
Holding thread has not terminated
Hex 01 =
Holding thread has terminated
Char(1)
179 B3 Reserved (binary 0) Char(13)
192 C0 Lock count UBin(8)
200 C8 Creator Char(8)
208 D0 Original mutex Space pointer
224 E0 Reserved (binary 0) Char(16)
240 F0 Wait list descriptors (repeated for each thread waiting for mutex) [*] Char(48)
240 F0
  • Waiter process ID
  • Char(30)
270 10E
  • Reserved (binary 0)
  • Char(2)
272 110
  • Waiter thread ID
  • Char(8)
280 118
  • Waiter unique thread value
  • Char(8)
*
*
--- End ---
 

The contents of the template fields are as defined for the previous template(s), unless specifically defined or redefined as follows:

The mutex owner process ID contains the name of the process containing the thread that holds the mutex lock. The name returned here is the 30-character PCS name. If this field is all blanks, the mutex is not locked or the thread that held the mutex lock has ended.

The last locker process ID contains the name of the process containing the thread that last locked the mutex after waiting for another thread to unlock the mutex. The name returned here is the 30-character PCS name. The last locker thread ID contains a process specific value that identifies the thread within the process that last locked the mutex after waiting for another thread to unlock the mutex. If last locker process ID is all blanks and last locker thread ID is binary 0, the last locker thread has ended or no thread has ever locked the mutex after waiting for another thread to unlock the mutex. The last locker unique thread value contains a system-wide unique value that identifies the specific thread that last locked the mutex after waiting for another thread to unlock the mutex. If this field is binary 0, no thread has ever locked the mutex after waiting for another thread to unlock the mutex. This field cannot be used as input on any other MI instruction, but may be useful for debug purposes.

A thread may perform LOCKMTX and immediately achieve the lock without waiting if there is no thread currently holding the lock. As a result, last locker process ID, last locker thread ID, and last locker unique thread value may contain information for a thread other than the one that last performed LOCKMTX on the mutex.

The last unlocker process ID contains the name of the process containing the thread that last unlocked the mutex while waking another thread that was waiting. The name returned here is the 30-character PCS name. The last unlocker thread ID contains a process specific value that identifies the thread within the process that last unlocked the mutex while waking another thread that was waiting. If last unlocker process ID is all blanks and last unlocker thread ID is binary 0, the last unlocker thread has ended or no thread has ever unlocked the mutex while waking another thread that was waiting. The last unlocker unique thread value contains a system-wide unique value that identifies the specific thread that last unlocked the mutex while waking another thread that was waiting. If this field is binary 0, no thread has ever unlocked the mutex while waking another thread that was waiting. This field cannot be used as input on any other MI instructions, but may be useful for debug purposes.

A thread may perform UNLKMTX and immediately unlock the mutex without waking another thread if there are no other threads waiting. As a result, last unlocker process ID, last unlocker thread ID, and last unlocker unique thread value may contain information for a thread other than the one that last performed UNLKMTX on the mutex.

The recursive flag indicates if this mutex was created with the recursive option. If recursive flag is set to recursive attempts to lock this mutex will not be permitted then the mutex cannot be locked recursively. If recursive flag is set to recursive attempts to lock this mutex will be permitted by the same thread that has already locked the mutex then the mutex can be locked multiple times.

The keep valid flag indicates if this mutex was created with the keep valid option. If keep valid flag is set to mutex will be destroyed when its owning thread is terminated then the mutex will be destroyed when a thread holding the lock on the mutex terminates. If keep valid flag is set to mutex will remain valid when its owning thread is terminated, then the mutex will be in a pending state when a thread holding the lock on the mutex terminates. The mutex will remain in the pending state until the next thread successfully locks and revalidates the mutex. The thread that successfully locks and revalidates the mutex receives the EUNKNOWN error number to indicate that the resource protected by this mutex may need special handling.

The pending state flag indicates if this mutex is currently in a state in which it must be revived because the thread that held the lock on this mutex terminated. This field is only valid when keep valid flag is set to mutex will remain valid when its owning thread is terminated. If pending state flag is set to holding thread has not terminated, then the mutex is not in a pending state because a thread holding the lock has terminated or the mutex for which the owning thread has terminated has been successfully revalidated. If pending state flag is set to holding thread has terminated, then the mutex is considered to be in a pending state. The mutex will remain in the pending state until the next thread successfully locks and revalidates the mutex. The thread that successfully locks and revalidates the mutex receives the EUNKNOWN error number to indicate that the resource protected by this mutex may need special handling. This field is reserved when keep valid flag is set to mutex will be destroyed when its owning thread is terminated.

The lock count field indicates the number of times the mutex is locked. If the mutex is created to be recursive, then a thread can hold multiple locks on the same mutex and this field may contain a value greater than one.

The creator is the first 8 characters of the name of the program module that created the mutex.

The original mutex is a space pointer to a mutex created by CRTMTX. If the mutex operand is the address of a mutex created by CRTMTX, original mutex is the same address as the mutex operand. If the mutex operand is the address of a replica, original mutex is the address of the mutex created by CRTMTX from which the replica was obtained. If the mutex operand is the address of a copy of a mutex, original mutex is the address of the mutex created by CRTMTX from which the copy was made. Copies of mutex copies are permitted; however, this field will point to the mutex created by CRTMTX from which the first copy was made. For mutexes that exist in teraspace storage, original mutex is returned only if the thread performing MATMTX is contained in the process that created the original mutex.

The wait list descriptors identify the threads waiting for the mutex to become unlocked. The waiter process ID contains the name of the process containing the waiting thread. The name returned here is the 30-character PCS name. If this field is all blanks, the thread waiting on the mutex has ended.

Authorization Required

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 10 Damage Encountered
    • 1002 Machine Context Damage State
    • 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
    • 2207 Authority Verification Terminated Due to Destroyed Object
    • 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
  • 32 Scalar Specification
    • 3203 Scalar Value Invalid
  • 36 Space Management
    • 3601 Space Extension/Truncation
  • 38 Template Specification
    • 3803 Materialization Length Invalid
    • 3804 Invalid Mutex
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed