Home | History | Annotate | Download | only in api
      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 &amp;= 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