1 # 2 # Copyright (C) 2015 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 header: 18 summary: Atomic Update Functions 19 description: 20 To update values shared between multiple threads, use the functions below. 21 They ensure that the values are atomically updated, i.e. that the memory 22 reads, the updates, and the memory writes are done in the right order. 23 24 These functions are slower than their non-atomic equivalents, so use 25 them only when synchronization is needed. 26 27 Note that in RenderScript, your code is likely to be running in separate 28 threads even though you did not explicitely create them. The RenderScript 29 runtime will very often split the execution of one kernel across multiple 30 threads. Updating globals should be done with atomic functions. If possible, 31 modify your algorithm to avoid them altogether. 32 end: 33 34 function: rsAtomicAdd 35 version: 14 36 ret: int32_t, "Value of *addr prior to the operation." 37 arg: volatile int32_t* addr, "Address of the value to modify." 38 arg: int32_t value, "Amount to add." 39 summary: Thread-safe addition 40 description: 41 Atomicly adds a value to the value at addr, i.e. <code>*addr += value</code>. 42 test: none 43 end: 44 45 function: rsAtomicAdd 46 version: 20 47 ret: int32_t 48 arg: volatile uint32_t* addr 49 arg: uint32_t value 50 test: none 51 end: 52 53 function: rsAtomicAnd 54 version: 14 55 ret: int32_t, "Value of *addr prior to the operation." 56 arg: volatile int32_t* addr, "Address of the value to modify." 57 arg: int32_t value, "Value to and with." 58 summary: Thread-safe bitwise and 59 description: 60 Atomicly performs a bitwise and of two values, storing the result back at addr, 61 i.e. <code>*addr &= value</code>. 62 test: none 63 end: 64 65 function: rsAtomicAnd 66 version: 20 67 ret: int32_t 68 arg: volatile uint32_t* addr 69 arg: uint32_t value 70 test: none 71 end: 72 73 function: rsAtomicCas 74 version: 14 75 ret: int32_t, "Value of *addr prior to the operation." 76 arg: volatile int32_t* addr, "Address of the value to compare and replace if the test passes." 77 arg: int32_t compareValue, "Value to test *addr against." 78 arg: int32_t newValue, "Value to write if the test passes." 79 summary: Thread-safe compare and set 80 description: 81 If the value at addr matches compareValue then the newValue is written at addr, 82 i.e. <code>if (*addr == compareValue) { *addr = newValue; }</code>. 83 84 You can check that the value was written by checking that the value returned 85 by rsAtomicCas() is compareValue. 86 test: none 87 end: 88 89 function: rsAtomicCas 90 version: 14 91 ret: uint32_t 92 arg: volatile uint32_t* addr 93 arg: uint32_t compareValue 94 arg: uint32_t newValue 95 test: none 96 end: 97 98 function: rsAtomicDec 99 version: 14 100 ret: int32_t, "Value of *addr prior to the operation." 101 arg: volatile int32_t* addr, "Address of the value to decrement." 102 summary: Thread-safe decrement 103 description: 104 Atomicly subtracts one from the value at addr. This is equivalent to <code>@rsAtomicSub(addr, 1)</code>. 105 test: none 106 end: 107 108 function: rsAtomicDec 109 version: 20 110 ret: int32_t 111 arg: volatile uint32_t* addr 112 test: none 113 end: 114 115 function: rsAtomicInc 116 version: 14 117 ret: int32_t, "Value of *addr prior to the operation." 118 arg: volatile int32_t* addr, "Address of the value to increment." 119 summary: Thread-safe increment 120 description: 121 Atomicly adds one to the value at addr. This is equivalent to <code>@rsAtomicAdd(addr, 1)</code>. 122 test: none 123 end: 124 125 function: rsAtomicInc 126 version: 20 127 ret: int32_t 128 arg: volatile uint32_t* addr 129 test: none 130 end: 131 132 function: rsAtomicMax 133 version: 14 134 ret: uint32_t, "Value of *addr prior to the operation." 135 arg: volatile uint32_t* addr, "Address of the value to modify." 136 arg: uint32_t value, "Comparison value." 137 summary: Thread-safe maximum 138 description: 139 Atomicly sets the value at addr to the maximum of *addr and value, i.e. 140 <code>*addr = max(*addr, value)</code>. 141 test: none 142 end: 143 144 function: rsAtomicMax 145 version: 14 146 ret: int32_t 147 arg: volatile int32_t* addr 148 arg: int32_t value 149 test: none 150 end: 151 152 function: rsAtomicMin 153 version: 14 154 ret: uint32_t, "Value of *addr prior to the operation." 155 arg: volatile uint32_t* addr, "Address of the value to modify." 156 arg: uint32_t value, "Comparison value." 157 summary: Thread-safe minimum 158 description: 159 Atomicly sets the value at addr to the minimum of *addr and value, i.e. 160 <code>*addr = min(*addr, value)</code>. 161 test: none 162 end: 163 164 function: rsAtomicMin 165 version: 14 166 ret: int32_t 167 arg: volatile int32_t* addr 168 arg: int32_t value 169 test: none 170 end: 171 172 function: rsAtomicOr 173 version: 14 174 ret: int32_t, "Value of *addr prior to the operation." 175 arg: volatile int32_t* addr, "Address of the value to modify." 176 arg: int32_t value, "Value to or with." 177 summary: Thread-safe bitwise or 178 description: 179 Atomicly perform a bitwise or two values, storing the result at addr, 180 i.e. <code>*addr |= value</code>. 181 test: none 182 end: 183 184 function: rsAtomicOr 185 version: 20 186 ret: int32_t 187 arg: volatile uint32_t* addr 188 arg: uint32_t value 189 test: none 190 end: 191 192 function: rsAtomicSub 193 version: 14 194 ret: int32_t, "Value of *addr prior to the operation." 195 arg: volatile int32_t* addr, "Address of the value to modify." 196 arg: int32_t value, "Amount to subtract." 197 summary: Thread-safe subtraction 198 description: 199 Atomicly subtracts a value from the value at addr, i.e. <code>*addr -= value</code>. 200 test: none 201 end: 202 203 function: rsAtomicSub 204 version: 20 205 ret: int32_t 206 arg: volatile uint32_t* addr 207 arg: uint32_t value 208 test: none 209 end: 210 211 function: rsAtomicXor 212 version: 14 213 ret: int32_t, "Value of *addr prior to the operation." 214 arg: volatile int32_t* addr, "Address of the value to modify." 215 arg: int32_t value, "Value to xor with." 216 summary: Thread-safe bitwise exclusive or 217 description: 218 Atomicly performs a bitwise xor of two values, storing the result at addr, 219 i.e. <code>*addr ^= value</code>. 220 test: none 221 end: 222 223 function: rsAtomicXor 224 version: 20 225 ret: int32_t 226 arg: volatile uint32_t* addr 227 arg: uint32_t value 228 test: none 229 end: 230
