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