1QBATOMIC.H(3) libqb Programmer's Manual QBATOMIC.H(3)
2
3
4
6 qbatomic.h - Basic atomic integer and pointer operations.
7
8
10 #include <qb/qbatomic.h>
11
13 The following functions can be used to atomically access integers and
14 pointers. They are implemented as inline assembler function on most
15 platforms and use slower fall-backs otherwise. Using them can sometimes
16 save you from using a performance-expensive pthread_mutex to protect
17 the integer or pointer.
18
19 The most important usage is reference counting. Using
20 qb_atomic_int_inc() and qb_atomic_int_dec_and_test() makes reference
21 counting a very fast operation.
22
23 You must not directly read integers or pointers concurrently accessed
24 by multiple threads, but use the atomic accessor functions instead.
25 That is, always use qb_atomic_int_get() and qb_atomic_pointer_get() for
26 read outs. They provide the necessary synchronization mechanisms like
27 memory barriers to access memory locations concurrently.
28
29 If you are using those functions for anything apart from simple refer‐
30 ence counting, you should really be aware of the implications of doing
31 that. There are literally thousands of ways to shoot yourself in the
32 foot. So if in doubt, use a pthread_mutex. If you don't know, what mem‐
33 ory barriers are, do not use anything but qb_atomic_int_inc() and
34 qb_atomic_int_dec_and_test().
35
36 It is not safe to set an integer or pointer just by assigning to it,
37 when it is concurrently accessed by other threads with the following
38 functions. Use qb_atomic_int_compare_and_exchange() or
39 qb_atomic_pointer_compare_and_exchange() respectively.
40
42 qb_atomic_int_set(3), qb_atomic_int_compare_and_exchange(3),
43 qb_atomic_int_get(3), qb_atomic_int_add(3), qb_atomic_init(3),
44 qb_atomic_pointer_get(3), qb_atomic_int_exchange_and_add(3),
45 qb_atomic_pointer_compare_and_exchange(3), qb_atomic_pointer_set(3)
46
48 Copyright (C) 2003 Sebastian Wilhelmi
49
50
51
52LIBQB 2021-11-12 QBATOMIC.H(3)