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