Check Lock Value (CHKLKVAL)

Built-in number for CHKLKVAL is 677.
CHKLKVAL (
           addr    : address of a signed binary(8) value  (has
                      alignment restrictions - see description below)
           old_val : signed binary(8) value
           new_val : signed binary(8) value
) : signed binary(4)

Description:   Performs the following atomic (uninterruptible) sequence of operations: The value pointed to by addr is compared to the old_val value. If the two values are equal, the new_val value is stored into the addr location and the numeric value 0 is returned. If the two values are not equal, the numeric value 1 is returned.

The first operand must be 8-byte aligned. Failure to have the first operand aligned properly will not be detected, but the results of the instruction are undefined when this occurs.

The comparison and conditional update of the first operand are performed atomically (not interruptible). This is important when multiple threads share the storage pointed to by addr. See Atomicity for additional information.

This operation is storage synchronizing. Any shared storage reads performed after a successful update of the lock value will be no less current than the most recent synchronizing action by the writer of the shared storage.

The behavior of this instruction is similar to the CMPSW instruction. CHKLKVAL is designed specifically for implementation of low-level locking protocols, and may perform better than using CMPSW for that purpose.

For correct storage synchronization, the CHKLKVAL instruction is commonly used in conjunction with the CLRLKVAL instruction.

See Storage Synchronization Concepts for additional information on storage synchronization.

Usage Notes

The CHKLKVAL and CLRLKVAL instructions are designed primarily to be used in combination when implementing low-level locking protocols to protect space data shared by two or more threads.

A typical usage pattern for these instructions is:

  // Acquire the lock
  loop until CHKLKVAL(LOCK, 0, 1) returns the value zero
 
  [ Shared data reads/writes go here ]
 
  // Release the "lock"
  CLRLKVAL(LOCK, 0)

Where:  

  LOCK        is the address of an 8-byte variable shared by threads
                that want to enforce mutually exclusive access to a
                shared data structure.

Note that the example above is only a framework that illustrates a simple locking protocol. When all threads which share a data structure use this pattern, access to the data structure will be synchronized and free of race conditions.

The values 0 and 1 used above do not have any particular meaning to the instruction. They are simply unique values that are used in this example to represent an unlocked and locked state, respectively.

Note also that the pattern above contains no provision for deadlock detection/prevention, as would be available with higher level MI locking mechanisms, such as the LOCKMTX and LOCKSL instructions.

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

• 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

• 2201 Object Not Found
• 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

2C Program Execution

• 2C04 Branch Target Invalid

36 Space Management

• 3601 Space Extension/Truncation

44 Protection Violation

• 4401 Object Domain or Hardware Storage Protection Violation
• 4402 Literal Values Cannot Be Changed