ATOMIC(2)                                               ATOMIC(2)

     NAME
          agetl, agetv, agetp, aswapl, aswapv, aswapp, aincl, aincv,
          acasl, acasv, acasp, coherence - atomic operations

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          typedef struct Along Along;
          typedef struct Avlong Avlong;
          typedef struct Aptr Aptr;

          long   agetl(Along *);
          vlong  agetv(Avlong *);
          void*  agetp(Aptr *);

          long   aswapl(Along *, long new);
          vlong  aswapv(Avlong *, vlong new);
          void*  aswapp(Aptr *, void* new);

          long   aincl(Along *, long);
          vlong  aincv(Avlong *, vlong);

          int    acasl(Along *, long old, long new);
          int    acasv(Avlong *, vlong old, vlong new);
          int    acasp(Aptr *, void* old, void* new);

          void   coherence(void);

     DESCRIPTION
          These routines provide atomic operations that can be used to
          synchronize processes.  They are sequentially consistent,
          that is, operations in a multi-process program are executed
          in some sequential order; operations in each process are
          executed in program order.  No non-atomic operations will be
          re-orded to be observable before or after an atomic
          operation.

          Agetl, agetv, and agetp perform an atomic read.  Aswapl,
          aswapv, and aswapp perform an atomic swap, replacing the
          value with new then returning the previous value.  Aincl and
          aincv perform an atomic add, replacing the value with the
          sum of it and new, then returning the result.

          Acasl, acasv, and acasp perform an atomic compare and swap.
          If the value is equal to old then it is replaced by new and
          the function returns 1.  If not, the function returns 0.

          Coherence provides only the re-ordering barrier.

     SOURCE
          /sys/src/libc/port/atomic64.c
          /sys/src/libc/$objtype/atomic.s
          /sys/src/libc/$objtype/atomic64.s

     BUGS
          The vlong operations may be emulated in software and there-
          fore must not be called from a note handler.

          Correct use of atomics is fundamentally hard, and they are
          generally to be avoided.  If the intent is to use them for
          anything other than refcounts and id generation, look to
          lock(2) for alternatives.