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).