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 operations we define
have the form
AO_<atomic-op>_<barrier> for all plausible
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 operations on
the applicable hardware. In many cases that will involve, for example, a
stronger memory barrier, or a combination of hardware primitives.
Note that atomicity guarantees are valid only if both readers and writers use
AO_ operations to access the shared value, while ordering constraints 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_ operations 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
returns 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).