Destroy Pointer-Based Mutex (DESMTX)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
03C7 Mutex Mutex destroy options Result
Operand 1: Space pointer.

Operand 2: Space pointer.

Operand 3: Signed binary(4) variable scalar.

Bound Program Access 
Built-in number for DESMTX is 162.
DESMTX (                                                                        
        mutex                   : address                                      
        mutex_destroy_options   : address of unsigned binary(4) value             
) :   signed binary(4)  /* result */
Note: The term mutex in this instruction refers to a pointer-based mutex.

Description:

The mutex whose address is referenced by operand 1 is destroyed. The mutex is set to binary zero. All threads currently in the mutex wait state for this mutex are removed from the wait state and an EDESTROYED error number result is returned to each waiting thread. The ETYPE error is returned when the mutex operand references a synchronization object that is not a pointer-based mutex.

The space pointed to by operand 2 contains the mutex destroy options.

Result is used to indicate the success or failure of the DESMTX instruction.

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 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 mutex destroy options referenced by operand 2 can have the following values:

Offset  
Dec Hex Field Name Data Type and Length
0
0
Mutex destroy options
0 =
Destroy mutex (this is the default option)
UBin(4)
4
4
--- End ---
 

The mutex destroy options should be set to 0 in order to destroy a mutex. The mutex will not be destroyed if it is locked by another thread. An attempt to destroy a mutex when another thread has it locked will result in an EBUSY error number result.

All other values for mutex destroy options are reserved and will cause an EINVAL error number result to be returned.

If operand 2 in a bound program is a null pointer value, the default mutex destroy options are used. Operand 2 in non-bound programs must be a pointer to mutex destroy options. 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 is destroyed by this instruction, then result is set to 0. If an error occurs, then the result is set to an error condition. The EINVAL error number is returned when an invalid operand 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 mutex must have been previously created by the CRTMTX instruction, or must be a copy of a mutex that was previously created by the CRTMTX instruction. Note that if mutex references a mutex copy, upon successful completion of the DESMTX instruction, it is the copy that is set to binary zero and not the original mutex created by the CRTMTX instruction from which the copy was made. Attempting to destroy a mutex that was not created or whose contents have been altered will cause one of the pointer specification exceptions to occur.

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 is set to one of the following:

EBUSY
3029 - Resource busy.
EINVAL
3021 - The value specified for the argument is not correct.
EPERM
3027 - Operation not permitted.
ETYPE
3493 - Object type mismatch.

A synchronization object that is not a pointer-based mutex already exists at this address.

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