Commit | Line | Data |
---|---|---|
1e494cf4 JB |
1 | /* |
2 | * Copyright (C) 2007 The Android Open Source Project | |
3 | * | |
4 | * Licensed under the Apache License, Version 2.0 (the "License"); | |
5 | * you may not use this file except in compliance with the License. | |
6 | * You may obtain a copy of the License at | |
7 | * | |
8 | * http://www.apache.org/licenses/LICENSE-2.0 | |
9 | * | |
10 | * Unless required by applicable law or agreed to in writing, software | |
11 | * distributed under the License is distributed on an "AS IS" BASIS, | |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
13 | * See the License for the specific language governing permissions and | |
14 | * limitations under the License. | |
15 | */ | |
16 | ||
17 | #ifndef ANDROID_CUTILS_ATOMIC_H | |
18 | #define ANDROID_CUTILS_ATOMIC_H | |
19 | ||
20 | #include <stdint.h> | |
21 | #include <sys/types.h> | |
22 | ||
23 | #ifdef __cplusplus | |
24 | extern "C" { | |
25 | #endif | |
26 | ||
27 | /* | |
28 | * A handful of basic atomic operations. The appropriate pthread | |
29 | * functions should be used instead of these whenever possible. | |
30 | * | |
31 | * The "acquire" and "release" terms can be defined intuitively in terms | |
32 | * of the placement of memory barriers in a simple lock implementation: | |
33 | * - wait until compare-and-swap(lock-is-free --> lock-is-held) succeeds | |
34 | * - barrier | |
35 | * - [do work] | |
36 | * - barrier | |
37 | * - store(lock-is-free) | |
38 | * In very crude terms, the initial (acquire) barrier prevents any of the | |
39 | * "work" from happening before the lock is held, and the later (release) | |
40 | * barrier ensures that all of the work happens before the lock is released. | |
41 | * (Think of cached writes, cache read-ahead, and instruction reordering | |
42 | * around the CAS and store instructions.) | |
43 | * | |
44 | * The barriers must apply to both the compiler and the CPU. Note it is | |
45 | * legal for instructions that occur before an "acquire" barrier to be | |
46 | * moved down below it, and for instructions that occur after a "release" | |
47 | * barrier to be moved up above it. | |
48 | * | |
49 | * The ARM-driven implementation we use here is short on subtlety, | |
50 | * and actually requests a full barrier from the compiler and the CPU. | |
51 | * The only difference between acquire and release is in whether they | |
52 | * are issued before or after the atomic operation with which they | |
53 | * are associated. To ease the transition to C/C++ atomic intrinsics, | |
54 | * you should not rely on this, and instead assume that only the minimal | |
55 | * acquire/release protection is provided. | |
56 | * | |
57 | * NOTE: all int32_t* values are expected to be aligned on 32-bit boundaries. | |
58 | * If they are not, atomicity is not guaranteed. | |
59 | */ | |
60 | ||
61 | /* | |
62 | * Basic arithmetic and bitwise operations. These all provide a | |
63 | * barrier with "release" ordering, and return the previous value. | |
64 | * | |
65 | * These have the same characteristics (e.g. what happens on overflow) | |
66 | * as the equivalent non-atomic C operations. | |
67 | */ | |
68 | int32_t android_atomic_inc(volatile int32_t* addr); | |
69 | int32_t android_atomic_dec(volatile int32_t* addr); | |
70 | int32_t android_atomic_add(int32_t value, volatile int32_t* addr); | |
71 | int32_t android_atomic_and(int32_t value, volatile int32_t* addr); | |
72 | int32_t android_atomic_or(int32_t value, volatile int32_t* addr); | |
73 | ||
74 | /* | |
75 | * Perform an atomic load with "acquire" or "release" ordering. | |
76 | * | |
77 | * This is only necessary if you need the memory barrier. A 32-bit read | |
78 | * from a 32-bit aligned address is atomic on all supported platforms. | |
79 | */ | |
80 | int32_t android_atomic_acquire_load(volatile const int32_t* addr); | |
81 | int32_t android_atomic_release_load(volatile const int32_t* addr); | |
82 | ||
83 | /* | |
84 | * Perform an atomic store with "acquire" or "release" ordering. | |
85 | * | |
86 | * This is only necessary if you need the memory barrier. A 32-bit write | |
87 | * to a 32-bit aligned address is atomic on all supported platforms. | |
88 | */ | |
89 | void android_atomic_acquire_store(int32_t value, volatile int32_t* addr); | |
90 | void android_atomic_release_store(int32_t value, volatile int32_t* addr); | |
91 | ||
92 | /* | |
93 | * Compare-and-set operation with "acquire" or "release" ordering. | |
94 | * | |
95 | * This returns zero if the new value was successfully stored, which will | |
96 | * only happen when *addr == oldvalue. | |
97 | * | |
98 | * (The return value is inverted from implementations on other platforms, | |
99 | * but matches the ARM ldrex/strex result.) | |
100 | * | |
101 | * Implementations that use the release CAS in a loop may be less efficient | |
102 | * than possible, because we re-issue the memory barrier on each iteration. | |
103 | */ | |
104 | int android_atomic_acquire_cas(int32_t oldvalue, int32_t newvalue, | |
105 | volatile int32_t* addr); | |
106 | int android_atomic_release_cas(int32_t oldvalue, int32_t newvalue, | |
107 | volatile int32_t* addr); | |
108 | ||
109 | /* | |
110 | * Aliases for code using an older version of this header. These are now | |
111 | * deprecated and should not be used. The definitions will be removed | |
112 | * in a future release. | |
113 | */ | |
114 | #define android_atomic_write android_atomic_release_store | |
115 | #define android_atomic_cmpxchg android_atomic_release_cas | |
116 | ||
117 | #ifdef __cplusplus | |
118 | } // extern "C" | |
119 | #endif | |
120 | ||
121 | #endif // ANDROID_CUTILS_ATOMIC_H |