NAME

       qbatomic.h - Basic atomic integer and pointer operations.

SYNOPSIS

       #include <qb/qbatomic.h>

DESCRIPTION

       The  following  functions can be used to atomically access integers and pointers. They are
       implemented as inline assembler function on  most  platforms  and  use  slower  fall-backs
       otherwise.   Using  them  can  sometimes  save  you  from  using  a  performance-expensive
       pthread_mutex to protect the integer or pointer.

       The  most  important  usage  is  reference   counting.   Using   qb_atomic_int_inc()   and
       qb_atomic_int_dec_and_test() makes reference counting a very fast operation.

       You must not directly read integers or pointers concurrently accessed by multiple threads,
       but use the atomic accessor functions instead. That is, always use qb_atomic_int_get() and
       qb_atomic_pointer_get()   for  read  outs.  They  provide  the  necessary  synchronization
       mechanisms like memory barriers to access memory locations concurrently.

       If you are using those functions for anything apart from simple  reference  counting,  you
       should really be aware of the implications of doing that. There are literally thousands of
       ways to shoot yourself in the foot. So if in doubt, use  a  pthread_mutex.  If  you  don't
       know,  what  memory  barriers  are,  do  not  use  anything  but  qb_atomic_int_inc()  and
       qb_atomic_int_dec_and_test().

       It is not safe to set an  integer  or  pointer  just  by  assigning  to  it,  when  it  is
       concurrently   accessed   by   other   threads   with   the   following   functions.   Use
       qb_atomic_int_compare_and_exchange()      or      qb_atomic_pointer_compare_and_exchange()
       respectively.

SEE ALSO

       qb_atomic_int_set(3), qb_atomic_int_compare_and_exchange(3), qb_atomic_int_get(3),
       qb_atomic_int_add(3), qb_atomic_init(3), qb_atomic_pointer_get(3),
       qb_atomic_int_exchange_and_add(3), qb_atomic_pointer_compare_and_exchange(3),
       qb_atomic_pointer_set(3)

COPYRIGHT

       Copyright (C) 2003 Sebastian Wilhelmi