1atomics(3)                 Erlang Module Definition                 atomics(3)
2
3
4

NAME

6       atomics - Atomic Functions
7

DESCRIPTION

9       This module provides a set of functions to do atomic operations towards
10       mutable atomic variables. The implementation utilizes only atomic hard‐
11       ware  instructions  without  any software level locking, which makes it
12       very efficient for concurrent access. The atomics  are  organized  into
13       arrays with the following semantics:
14
15         * Atomics are 64 bit integers.
16
17         * Atomics can be represented as either signed or unsigned.
18
19         * Atomics wrap around at overflow and underflow operations.
20
21         * All  operations guarantee atomicity. No intermediate results can be
22           seen. The result of one mutation can only be the input to one  fol‐
23           lowing mutation.
24
25         * All  atomic operations are mutually ordered. If atomic B is updated
26           after atomic A, then that is how it will appear to  any  concurrent
27           readers.  No  one can read the new value of B and then read the old
28           value of A.
29
30         * Indexes into atomic arrays are one-based. An atomic array of  arity
31           N contains N atomics with index from 1 to N.
32

DATA TYPES

34       atomics_ref()
35
36              Identifies an atomic array returned from new/2.
37

EXPORTS

39       new(Arity, Opts) -> atomics_ref()
40
41              Types:
42
43                 Arity = integer() >= 1
44                 Opts = [Opt]
45                 Opt = {signed, boolean()}
46
47              Create  a  new  array of Arity number of atomics. All atomics in
48              the array are initially set to zero.
49
50              Argument Opts is a list of the following possible options:
51
52                {signed, boolean()}:
53                  Indicate if the elements of the array  will  be  treated  as
54                  signed or unsigned integers. Default is true (signed).
55
56                  The integer interval for signed atomics are from -(1 bsl 63)
57                  to (1 bsl 63)-1 and for unsigned atomics from 0  to  (1  bsl
58                  64)-1.
59
60              Atomics  are  not  tied to the current process and are automati‐
61              cally garbage collected when they are no longer referenced.
62
63       put(Ref, Ix, Value) -> ok
64
65              Types:
66
67                 Ref = atomics_ref()
68                 Ix = Value = integer()
69
70              Set atomic to Value.
71
72       get(Ref, Ix) -> integer()
73
74              Types:
75
76                 Ref = atomics_ref()
77                 Ix = integer()
78
79              Read atomic value.
80
81       add(Ref, Ix, Incr) -> ok
82
83              Types:
84
85                 Ref = atomics_ref()
86                 Ix = Incr = integer()
87
88              Add Incr to atomic.
89
90       add_get(Ref, Ix, Incr) -> integer()
91
92              Types:
93
94                 Ref = atomics_ref()
95                 Ix = Incr = integer()
96
97              Atomic addition and return of the result.
98
99       sub(Ref, Ix, Decr) -> ok
100
101              Types:
102
103                 Ref = atomics_ref()
104                 Ix = Decr = integer()
105
106              Subtract Decr from atomic.
107
108       sub_get(Ref, Ix, Decr) -> integer()
109
110              Types:
111
112                 Ref = atomics_ref()
113                 Ix = Decr = integer()
114
115              Atomic subtraction and return of the result.
116
117       exchange(Ref, Ix, Desired) -> integer()
118
119              Types:
120
121                 Ref = atomics_ref()
122                 Ix = Desired = integer()
123
124              Atomically replaces the value of the atomic with Desired and re‐
125              turns the value it held previously.
126
127       compare_exchange(Ref, Ix, Expected, Desired) -> ok | integer()
128
129              Types:
130
131                 Ref = atomics_ref()
132                 Ix = Expected = Desired = integer()
133
134              Atomically  compares  the atomic with Expected, and if those are
135              equal, set atomic to Desired. Returns ok if Desired was written.
136              Returns the actual atomic value if not equal to Expected.
137
138       info(Ref) -> Info
139
140              Types:
141
142                 Ref = atomics_ref()
143                 Info =
144                     #{size := Size, max := Max, min := Min, memory := Memory}
145                 Size = integer() >= 0
146                 Max = Min = integer()
147                 Memory = integer() >= 0
148
149              Return  information  about an atomic array in a map. The map has
150              the following keys:
151
152                size:
153                  The number of atomics in the array.
154
155                max:
156                  The highest possible value an atomic in this array can hold.
157
158                min:
159                  The lowest possible value an atomic in this array can hold.
160
161                memory:
162                  Approximate memory consumption for the array in bytes.
163
164
165
166Ericsson AB                       erts 12.1.5                       atomics(3)