sync(3C)

NAME
     sync, __fetch_and_add, __fetch_and_sub, __fetch_and_or,
     __fetch_and_and, __fetch_and_xor, __fetch_and_nand, __add_and_fetch,
     __sub_and_fetch, __or_and_fetch, __and_and_fetch, __xor_and_fetch,
     __nand_and_fetch, __compare_and_swap, __synchronize,
     __lock_test_and_set, __lock_acquire, __lock_release - C
     synchronization primitives for multiprocessing

SYNOPSIS
     See summaries in DESCRIPTION

DESCRIPTION
     The intrinsics described here provide a variety of primitive
     synchronization operations.  Besides performing the particular
     synchronization operation, each of these intrinsics has two key
     properties:

     1. The function performed is guaranteed to be atomic (typically
        achieved by implementing the operation using a sequence of load-
        linked/store-conditional instructions in a loop).

     2. Associated with each instrinsic are certain memory barrier
        properties that restrict the movement of memory references to
        visible data across the intrinsic operation (by either the compiler
        or the processor).

        A visible memory reference is a reference to a data object
        potentially accessible by another thread executing in the same
        shared address space. A visible data object may be one of the
        following:

        *  C/C++ global data

        *  Fortran COMMON data

        *  Data declared extern

        *  Volatile data

        *  Static data (either file-scope or function-scope)

        *  Data accessible via function parameters

        *  Automatic data (local-scope) that has had its address taken and
           assigned to some object which is visible (recursively)

     The memory barrier semantics of an intrinsic may be one of the
     following three types:

     acquire barrier
          Disallows the movement of memory references to visible data from
          after the intrinsic (in program order) to before the intrinsic
          (this behavior is desirable at lock-acquire operations, hence the
          name).

     release barrier
          Disallows the movement of memory references to visible data from
          before the intrinsic (in program order) to after the intrinsic
          (this behavior is desirable at lock-release operations, hence the
          name).

     full barrier
          disallows the movement of memory references to visible data past
          the intrinsic (in either direction), and is thus both an acquire
          and a release barrier. A barrier only restricts the movement of
          memory references to visible data across the intrinsic operation:
          between synchronization operations (or in their absence), memory
          references to visible data may be freely reordered subject to the
          usual data-dependence constraints.

     Caution: Conditional execution of a synchronization intrinsic (such as
     within a if or a while statement) does not prevent the movement of
     memory references to visible data past the overall if or while
     construct.

   Atomic fetch-and-op Operations
          "type __fetch_and_add (type* ptr, type value, ...)"

          "type __fetch_and_sub (type* ptr, type value, ...)"

          "type __fetch_and_or  (type* ptr, type value, ...)"

          "type __fetch_and_and (type* ptr, type value, ...)"

          "type __fetch_and_xor (type* ptr, type value, ...)"

          "type __fetch_and_nand(type* ptr, type value, ...)"

     Where type may be one of int, long, long long, unsigned int, unsigned
     long, or unsigned long long.  The ellipses (...) refers to an optional
     list of variables protected by the memory barrier.

     Behavior:

     * Atomically performs the specified operation with the given value on
       *ptr, and returns the old value of *ptr, as in the following
       example:

          { tmp = *ptr; *ptr <op>= value; return tmp; }

     * Full barrier.

   Atomic op-and-fetch Operations
          "type __add_and_fetch (type* ptr, type value, ...)"

          "type __sub_and_fetch (type* ptr, type value, ...)"

          "type __or_and_fetch  (type* ptr, type value, ...)"

          "type __and_and_fetch (type* ptr, type value, ...)"

          "type __xor_and_fetch (type* ptr, type value, ...)"

          "type __nand_and_fetch(type* ptr, type value, ...)"

     Where type may be one of int, long, long long, unsigned int, unsigned
     long, or unsigned long long.  The ellipses (...) refers to an optional
     list of variables protected by the memory barrier.

     Behavior:

     * Atomically performs the specified operation with the given value on
       *ptr, and returns the new value of *ptr. (i.e.)

          { *ptr <op>= value; return *ptr; }

     * Full barrier.

   Atomic compare-and-swap Operation
    "int __compare_and_swap (type* ptr, type oldvalue, type newvalue, ...)"

     Where type may be one of int, long, long long, unsigned int, unsigned
     long, or unsigned long long.  The ellipses (...) refers to an optional
     list of variables protected by the memory barrier.

     Behavior:

     * Atomically do the following: compare *ptr to oldvalue. If equal,
       store the new value and return 1, otherwise return 0. (i.e.)

          if (*ptr != oldvalue) return 0;

          else {

                  *ptr = newvalue;

                  return 1;
          }

     * Full barrier.

   Atomic synchronize Operation
          "__synchronize (...)"

     The ellipses (...) refers to an optional list of variables protected
     by the memory barrier.

     Behavior:

     * Full barrier

   Atomic lock-test-and-set Operation
          "type __lock_test_and_set (type* ptr, type value, ...)"

     Where type may be one of int, long, long long, unsigned int, unsigned
     long, or unsigned long long.  The ellipses (...) refers to an optional
     list of variables protected by the memory barrier.

     Behavior:

     * Atomically store the supplied value in *ptr and return the old value
       of *ptr. (i.e.)

          { tmp = *ptr; *ptr = value; return tmp; }

     * Acquire barrier.

   Atomic lock_release Operation
          "void __lock_release (type* ptr, ...)"

     Where type may be one of int, long, long long, unsigned int, unsigned
     long, or unsigned long long.  The ellipses (...) refers to an optional
     list of variables protected by the memory barrier.

     Behavior:

     * Set *ptr to 0.  (i.e.) { *ptr = 0 }

     * Release barrier.