LIBATOMIC-OPS(3) LIBATOMIC-OPS(3)
NAME
libatomic-ops - Library providing user level atomic operations
SYNOPSIS
#include <atomic_ops.h>
cc ... -latomic_ops
Note that all operations have an additional barrier option that can be
set explicitly.
void AO_load(AO_t *addr)
void AO_store(AO_t *addr, AO_t val)
int AO_test_and_set (AO_t *addr)
AO_t AO_fetch_and_add(AO_t *addr, AO_t incr)
AO_t AO_fetch_and_add1(AO_t *addr)
AO_t AO_fetch_and_sub1(AO_t *addr)
void AO_or(AO_t *p, AO_t incr)
int AO_compare_and_swap(AO_t *addr, AO_t old, AO_t new_val)
DESCRIPTION
libatomic-ops offers a programming interface to a comprehensive range
of atomic operations at user level.
We define various atomic operations on memory in a machine-specific
way. Unfortunately, this is complicated by the fact that these may or
may not be combined with various memory barriers. Thus the actual op-
erations we define have the form AO_<atomic-op>_<barrier> for all plau-
sible combinations of <atomic-op> and <barrier>.
The valid barrier suffixes are
_release
Earlier operations may not be delayed past it.
_acquire
Later operations may not move ahead of it.
_read Subsequent reads must follow this operation and preceding reads.
_write Earlier writes precede both this operation and later writes.
_full Ordered with respect to both earlier and later memops.
_release_write
Ordered with respect to earlier writes.
_acquire_read
Ordered with repsect to later reads.
This of course results in a mild combinatorial explosion.
The library will find the least expensive way to implement your opera-
tions on the applicable hardware. In many cases that will involve, for
example, a stronger memory barrier, or a combination of hardware primi-
tives.
Note that atomicity guarantees are valid only if both readers and writ-
ers use AO_ operations to access the shared value, while ordering con-
straints are intended to apply all memory operations. If a location
can potentially be accessed simultaneously from multiple threads, and
one of those accesses may be a write access, then all such accesses to
that location should be through AO_ primitives. However if AO_ opera-
tions enforce sufficient ordering to ensure that a location x cannot be
accessed concurrently, or can only be read concurrently, then x can be
accessed via ordinary references and assignments.
All operations operate on an AO_t value, which is the natural word size
for the architecture.
AO_load and AO_store load and store the specified pointer address.
AO_test_and_set atomically replaces an address with AO_TS_SET and re-
turns the prior value. An AO_TS_t location can be reset with the
AO_CLEAR macro, which usually uses AO_store_release
AO_fetch_and_add takes an address and a value to add.
AO_fetch_and_add1 and AO_fetch_and_sub1 are provided since they may
have faster implemenations on some hardware
AO_or atomically ors an AO_t value into a memory location, but does not
provide access to the original
AO_compare_and_swap takes an address, an old value and a new value and
returns an int. non-zero indicates the compare and swap succeeded.
SEE ALSO
libatomic-stack(3), libatomic-malloc(3)
AUTHOR
This manual page was written by Ian Wienand <ianw@gelato.unsw.edu.au>,
based on comments in the source code. It was written for the Debian
project (but may be used by others).
Ian Wienand May 17, 2005 LIBATOMIC-OPS(3)
Generated by dwww version 1.15 on Tue Jun 25 08:01:52 CEST 2024.