compare_and_swap Kernel Services

Purpose

Conditionally updates or returns a variable atomically.

Syntax

#include <sys/atomic_op.h>

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

boolean_t compare_and_swaplp ( addr,  old_val_addr,  new_val)
atomic_l addr;
long * old_val_addr;
long new_val;

Parameters

Item Description
addr Specifies the address of the variable.
old_val_addr Specifies the address of the old value to be checked against (and conditionally updated with) the value of the variable.
new_val Specifies the new value to be conditionally assigned to the variable.

Description

The compare_and_swap kernel services performs an atomic (uninterruptible) operation which compares the contents of a variable with a stored old value; if equal, a new value is stored in the variable, and TRUE is returned, otherwise the old value is set to the current value of the variable, and FALSE is returned.

The compare_and_swap kernel service operates on a single word (32 bit) variable while the compare_and_swaplp kernel service operates on a double word (64 bit) variable.

The compare_and_swap kernel services are particularly useful in operations on singly linked lists, where a list pointer must not be updated if it has been changed by another thread since it was read.

Note:
  • The single word variable passed to the compare_and_swap kernel service must be aligned on a full word (32 bit) boundary.
  • The double word variable passed to the compare_and_swaplp kernel service must be aligned on a double word (64 bit) boundary.

Execution Environment

The compare_and_swap kernel services can be called from either the process or interrupt environment.

Return Values

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