Compare and Swap (CMPSW)

Operand 2: Character(1,2,4,8) variable scalar.

Operand 3: Character(1,2,4,8) scalar.

Operand 4 [4-5]:

• Branch Form-Instruction number, relative instruction number, branch point, or instruction pointer.

• Indicator Form-Numeric variable scalar or character variable scalar.

Built-in number for CMPSWP is 156.
CMPSWP (
        op1   : address of a scalar(1,2,4,8) value
        op2   : address of a scalar(1,2,4,8) value (has alignment
                restrictions based on the length of the scalar - see
                description below)
        op3   : scalar(1,2,4,8) value
        cntl  : signed binary(4) literal value   (this operand
                is optional -- see description below)
) :   signed binary(4)

Description:   The value of the first compare operand is compared with the value of the second compare operand. If they are equal, the swap operand is stored in the second compare operand's location. If they are unequal, the second compare operand is stored into the first compare operand's location. Based on the comparison, the resulting condition is used with the extender field to:

• Transfer control conditionally to the instruction indicated in one of the branch target operands (branch form).

• Assign a value to each of the indicator operands (indicator form).

When an equal comparison occurs, it is assured that no access by another Compare and Swap instruction will occur at the second compare operand location between the moment that the second compare operand is fetched for comparison and the moment that the swap operand is stored at the second compare operand location.

When an unequal comparison occurs, no atomicity guarantees are made regarding the store to the first compare operand location and other Compare and Swap instruction access. Thus only the second compare operand should be a variable shared for concurrent processing control.

Both compare operands must be 1, 2, 4 or 8 byte character variable scalars and the swap operand must be a 1, 2, 4 or 8 byte character scalar. All three operands must have the same length. Failure to have the operands the same length will not be detected and the results of the Compare and Swap instruction are undefined when this occurs. The second operand must be aligned based on its length:

• one byte length - no alignment restrictions

• two byte length - halfword aligned

• four byte length - fullword aligned

• eight byte length - doubleword aligned

For bound program access, the cntl operand is optional, and does not need to be specified. If the cntl operand is specified, it has the following effect depending on the value:

• Hex 0x0 = (Default) Storage synchronization is performed both before and after a successful store of the swap operand.

• Hex 0x1 = No storage synchronization is performed

If the cntl operand is not specified, the instruction proceeds as if the default value had been specified.

The machine does not enforce that only the values enumerated above are used for the cntl operand. When specified, use of any value other than those enumerated above may result in unpredictable behavior.

Storage Synchronization

Unless explicitly disabled with the no storage synchronization is performed control option (disabling is possible only using bound program access), this instruction synchronizes storage both before and after the swap operand is stored to op2. Synchronized operation provides the following guarantees:

• When reading shared storage after a successful store of the swap operand, the thread performing the CMPSW will have a view of shared storage no less current then the most recent synchronizing actions taken by threads writing the shared storage.

• Shared data written by the thread performing the CMPSW prior to a successful store of the swap operand will be current from the perspective of other threads at their next synchronizing action.

When synchronization is disabled for CMPSW, storage synchronization can be accomplished using other storage synchronizing MI instructions, such as SYNCSTG.

See Storage Synchronization Concepts for additional information on storage synchronization.

Usage Note

Note that the compare and swap construct (including both this CMPSW instruction and support found on other architectures) simply compares values; it cannot determine whether the presence of the same value indicates that the data object for which an update is being synchronized is in fact the intended data object.

For example, CMPSW is insufficient for modifications to data structures comprised of multiple data objects, when an equal comparison of the value of one data object does not necessarily mean that the whole data structure is unchanged. In that case, finding an equal value for one data object may not mean that you are operating on the intended data structure element; other data objects in the data structure may have been independently changed.

A similar example is that CMPSW might not be sufficient for dequeueing an element from a queue residing in shared storage. More specifically, consider a queue that has an identified "head" offset value and some number of elements that each include a "next" offset field (a binary data object). Just because the element currently at the head of the queue has the same offset value as was previously copied to local storage for use in a CMPSW does not mean that the element's current value of "next" is the same as the "next" value copied to local storage when the "head" offset value was copied. That is, multiple elements may have been dequeued and the element with the saved "head" offset, but a different "next" value, may have been enqueued since the local copies were made. Setting the new queue head value with the copied "next" value would thus be invalid. Update of the queue data structure clearly has not been properly synchronized by such a use of CMPSW. Instead, a CMPSW of a data object that consists of two smaller data objects: an offset and a use count that is incremented every time the element is used, would be a safe approach if the use count values will always be different.

Resultant Conditions:  

• Equal-The first compare operand is equal to the second compare operand.

• Unequal -The first compare operand is unequal to the second compare operand.

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