Destroy Pointer-Based Mutex (DESMTX)


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
UBin(4)



0 = Destroy mutex (this is the default option)



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

Lock Enforcement

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

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

44 Protection Violation