Materialize Process Mutex (MATPRMTX)

Bound program access
Built-in number for MATPRMTX is 164.
MATPRMTX (
          operand1   : address
          operand2   : address of system pointer OR
                       address of space pointer(16) OR
                       null pointer value
          operand3   : 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 mutex lock and/or wait status of the thread or threads specified by operand 2 is materialized into the receiver space specified by operand 1. Operand 2 is the address of a process control space system pointer, the address of a space pointer or a null pointer value. If operand 2 is the address of a process control space system pointer, mutex status is returned for the initial thread of the process, or optionally, mutex status is returned for multiple threads in the process. If operand 2 is the address of a space pointer to a thread handle, mutex status is returned for the thread specified by the thread handle, or optionally, mutex status is returned for multiple threads in the same process as the specified thread. If operand 2 is a null pointer value, mutex status is returned for the issuing thread, or optionally, mutex status is returned for multiple threads in the same process as the issuing thread. If operand 2 references a process that is not a valid process, a process control space not associated with a process  (hex 2802) exception is signaled. If operand 2 references a thread handle that is not valid, a thread handle not associated with an active thread  (hex 2804) exception is signaled. For the specified thread or threads, the materialization identifies each mutex for which the thread holds a mutex lock and/or for which the thread is waiting, if any. The use of the MATPRMTX instruction to obtain information for threads in another process requires that the issuing thread be contained in the process that initiated the specified thread's process, or requires that the issuing thread have process control special authorization defined in its user profile or in a currently adopted user profile. If the issuing thread does not have the necessary authorization, a special authorization required  (hex 0A04) exception is signaled. The space pointed to by operand 3 is a 4-byte unsigned binary field used to indicate the type of information that should be returned by this instruction.

The materialization options value referenced by operand 3 has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Mutex reference option
Bit 0



0 = Return addresses of mutexes
1 = Return replicas of mutexes


0 0
Materialize threads option
Bit 1



0 = Materialize only specified thread
1 = Materialize multiple threads in specified thread's process


0 0
Mutex attributes option
Bit 2



0 = Do not return additional mutex attributes
1 = Return additional mutex attributes


0 0
Reserved (binary 0)
Bit 3
0 0
Thread status option
Bit 4



0 = Materialize holding and waiting threads
1 = Materialize only waiting threads


0 0
Reserved (binary 0)
Bits 5-31
4 4
--- End ---

If mutex reference option is set to return addresses of mutexes, then the materialization template will contain the addresses of the mutexes which are being described. If mutex reference option is set to return replicas of mutexes, then the materialization template will contain replicas of the mutexes which are being described. A replica is a mechanism used to obtain mutex information for mutexes that reside outside the addressability of the issuing thread. The address of a mutex or the address of a replica can be passed to the MATMTX instruction for further materialization. However, a replica can only be used to materialize a mutex, it cannot be used to perform any operation on the mutex that could change its state.

If the mutex reference option is set to return addresses of mutexes, only those mutexes that the issuing thread has addressability to can be materialized. If the mutex reference option is set to return replicas of mutexes, all mutexes for the specified thread(s) can be materialized. Addressable mutexes are mutexes that exist outside of a teraspace, or exist in the teraspace of the issuing thread. Mutexes that exist in teraspace other than the teraspace of the issuing thread are not eligible to be materialized if the mutex reference option is set to return addresses of mutexes, but are eligible to be materialized if the mutex reference option is set to return replicas of mutexes. Copies of mutexes are not materialized, regardless of addressability. See the CRTMTX instruction for additional information regarding mutex copies.

The materialize threads option field is used to select if mutex status is to be returned for only the specified thread, or for each thread in the same process as the specified process or thread. If materialize threads option is set to materialize only specified thread, then mutex status can be returned for only the specified thread. If materialize threads option is set to materialize multiple threads in specified thread's process, then mutex status can be returned for each thread in the same process as the specified process or thread. For a specified thread, or each of multiple threads, mutex status can only be returned if the thread meets the criteria specified by the thread status option.

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.

The thread status option field is used to selectively determine if a thread can be materialized based on its mutex status. If thread status option is set to materialize holding and waiting threads, then status can be returned for the specified thread or threads if the thread is holding a mutex lock and/or is waiting on a mutex. If thread status option is set to materialize only waiting threads, then status can be returned for the specified thread or threads only if the thread is waiting on a mutex.

If operand 3 is a null pointer value, the default materialization options (binary 0) 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 materialization template identified by operand 1 must be 16-byte aligned. If the materialization template is not properly aligned, a boundary alignment  (hex 0602) exception is signaled. 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 materialize threads option is set to materialize only specified thread and 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
Number of mutex lock entries
Bin(4)
12 C
Reserved (binary 0)
Char(4)
16 10
Mutex descriptors (repeated for each mutex currently held locked or waited for by the thread)
[*] Char(32)
16 10
Mutex
Space pointer or open pointer
32 20
Mutex state being described
Char(1)



Hex 00 = The mutex is held by the thread
Hex 01 = The thread is waiting to acquire the mutex


33 21
Reserved (binary 0)
Char(15)
* *
--- 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 mutex 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 mutex lock entries is the number of mutexes the materialized thread currently holds locked and/or is waiting for.

The mutex descriptors identify the mutexes the materialized thread either holds (acquired the lock on) or is waiting for. Depending on the setting of mutex reference option, the mutex field contains either the address of the mutex being described or a replica of the mutex being described. The mutex state being described field identifies how this mutex relates to the thread being materialized.

The materialization template has the following extended format when materialize threads option is set to materialize only specified thread and mutex attributes option is set to 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
Number of mutex lock entries
Bin(4)
12 C
Reserved (binary 0)
Char(4)
16 10
Mutex descriptors (repeated for each mutex currently held locked or waited for by the thread)
[*] Char(112)
16 10
Mutex
Space pointer or open pointer
32 20
Mutex state being described
Char(1)



Hex 00 = The mutex is held by the thread
Hex 01 = The thread is waiting to acquire the mutex


33 21
Reserved (binary 0)
Char(15)
48 30
Mutex name
Char(16)
64 40
Mutex holder process ID
Char(30)
94 5E
Reserved (binary 0)
Char(2)
96 60
Mutex holder thread ID
Char(8)
104 68
Mutex holder unique thread value
Char(8)
112 70
Number of waiters
Bin(4)
116 74
Reserved (binary 0)
Char(12)
* *
--- End ---

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

The mutex name field 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 holder process ID is 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. The mutex holder thread ID contains a process specific value that identifies the thread within the process that holds the mutex lock. The mutex holder unique thread value contains a system-wide unique value that identifies the specific thread that holds the mutex lock. This field cannot be used as input on any other MI instruction, but may be useful for debug purposes. The number of waiters is the number of threads that are currently waiting for the mutex to be unlocked.

The materialization template has the following standard format when materialize threads option is set to materialize multiple threads in specified thread's process and 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
Number of threads in process
UBin(4)
12 C
Number of thread mutex descriptors
UBin(4)
16 10
Thread mutex descriptors (repeated for each mutex currently held locked or waited for by each identified thread)
[*] Char(48)
16 10
Identified thread ID
Char(8)
24 18
Number of descriptors for identified thread
UBin(4)
28 1C
Descriptor entry number for identified thread
UBin(4)
32 20
Mutex descriptor
Char(32)
32 20
Mutex
Space pointer or open pointer
48 30
Mutex state being described
Char(1)



Hex 00 = The mutex is held by the thread
Hex 01 = The thread is waiting to acquire the mutex


49 31
Reserved (binary 0)
Char(15)
* *
--- End ---

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

The number of threads in process is the total number of active threads in the process found at the time of materialization. The actual number of threads materialized may be less than this number since only threads that are associated with at least one mutex will have their mutex information described. A thread has a mutex association if it has at least one mutex locked and/or is waiting on a mutex. The actual number of threads materialized may also be less than this number if the number of bytes provided is insufficient to contain all of the mutex information for each thread in the process having a mutex association.

The number of thread mutex descriptors is the combined total number of thread mutex descriptors that were actually returned for all the threads in the process. The number of descriptors returned for each thread varies depending on the number of mutexes an individual thread is associated with, that is, the number of mutexes the thread has locked and/or is waiting for. If the number of bytes provided is insufficient to contain all of the mutex information for all of the threads in the process, then as many mutex descriptors are returned for as many threads as possible. Partial descriptors are not returned.

The thread mutex descriptors identify the threads that are associated with one or more mutexes, and describe each mutex associated with each thread. One thread mutex descriptor is returned for each mutex associated with a given thread, so the same thread can have multiple descriptors. The selection of descriptors to be returned for a specified thread or threads is determined by the mutex association criteria specified by the thread status option. The identified thread ID field contains a process specific value that identifies the thread that is associated with a particular descriptor. The number of descriptors for identified thread field contains the number of possible descriptors that can be returned for the identified thread. The descriptor entry number for identified thread field uniquely identifies each descriptor returned for the identified thread. For each descriptor associated with the same thread, the identified thread ID and number of descriptors for identified thread fields will contain the same values, but the descriptor entry number will be sequentially different. The combination of these three fields effectively organizes the mutex information returned for each thread into a "descriptor M of N" format where "M" is the descriptor entry number for identified thread and "N" is the number of descriptors for identified thread.

The materialization template has the following extended format when materialize threads option is set to materialize multiple threads in specified thread's process and mutex attributes option is set to 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
Number of threads in process
UBin(4)
12 C
Number of thread mutex descriptors
UBin(4)
16 10
Thread mutex descriptors (repeated for each mutex currently held locked or waited for by each identified thread)
[*] Char(128)
16 10
Identified thread ID
Char(8)
24 18
Number of descriptors for identified thread
UBin(4)
28 1C
Descriptor entry number for identified thread
UBin(4)
32 20
Mutex descriptor
Char(112)
32 20
Mutex
Space pointer or open pointer
48 30
Mutex state being described
Char(1)



Hex 00 = The mutex is held by the thread
Hex 01 = The thread is waiting to acquire the mutex


49 31
Reserved (binary 0)
Char(15)
64 40
Mutex name
Char(16)
80 50
Mutex holder process ID
Char(30)
110 6E
Reserved (binary 0)
Char(2)
112 70
Mutex holder thread ID
Char(8)
120 78
Mutex holder unique thread value
Char(8)
128 80
Number of waiters
Bin(4)
132 84
Reserved (binary 0)
Char(12)
* *
--- End ---

The contents of the template fields are as defined for the previous template(s).

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

28 Process/Thread State

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation