compare_and_swap Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

compare_and_swap Subroutine

Purpose

Conditionally updates or returns a single word variable atomically.

Library

Standard C library (libc.a)

Syntax

#include <sys/atomic_op.h>

boolean_t compare_and_swap (word_addr, old_val_addr, new_val)
atomic_p word_addr;
int *old_val_addr;
int new_val;

Description

The compare_and_swap subroutine performs an atomic operation which compares the contents of a single word variable with a stored old value. If the values are equal, a new value is stored in the single word variable and TRUE is returned; otherwise, the old value is set to the current value of the single word variable and FALSE is returned.

The compare_and_swap subroutine is useful when a word value must be updated only if it has not been changed since it was last read.

Note: The word containing the single word variable must be aligned on a full word boundary.

Note: If compare_and_swap is used as a locking primitive, insert an isync at the start of any critical sections.

Parameters

word_addr	Specifies the address of the single word variable.
old_val_addr	Specifies the address of the old value to be checked against (and conditionally updated with) the value of the single word variable.
new_val	Specifies the new value to be conditionally assigned to the single word variable.

Return Values

TRUE	Indicates that the single word variable was equal to the old value, and has been set to the new value.
FALSE	Indicates that the single word variable was not equal to the old value, and that its current value has been returned in the location where the old value was previously stored.

Implementation Specifics

The compare_and_swap subroutine is part of the Base Operating System (BOS) Runtime.

Related Information

The fetch_and_add subroutine, fetch_and_and subroutine, fetch_and_or subroutine.