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

NAME

6       counters - Counter Functions
7

DESCRIPTION

9       This module provides a set of functions to do operations towards shared
10       mutable counter variables. The  implementation  does  not  utilize  any
11       software  level  locking,  which makes it very efficient for concurrent
12       access. The counters are organized into arrays with the  following  se‐
13       mantics:
14
15         * Counters are 64 bit signed integers.
16
17         * Counters wrap around at overflow and underflow operations.
18
19         * Counters are initialized to zero.
20
21         * Write  operations  guarantee atomicity. No intermediate results can
22           be seen from a single write operation.
23
24         * Two types of counter arrays can be created with options atomics  or
25           write_concurrency.  The atomics counters have good allround perfor‐
26           mance with nice consistent semantics while write_concurrency  coun‐
27           ters offers even better concurrent write performance at the expense
28           of some potential read inconsistencies. See new/2.
29
30         * Indexes into counter arrays are one-based. A counter array of  size
31           N contains N counters with index from 1 to N.
32

DATA TYPES

34       counters_ref()
35
36              Identifies a counter array returned from new/2.
37

EXPORTS

39       new(Size, Opts) -> counters_ref()
40
41              Types:
42
43                 Size = integer() >= 1
44                 Opts = [Opt]
45                 Opt = atomics | write_concurrency
46
47              Create a new counter array of Size counters. All counters in the
48              array are initially set to zero.
49
50              Argument Opts is a list of the following possible options:
51
52                atomics (Default):
53                  Counters will be sequentially consistent. If write operation
54                  A is done sequentially before write operation B, then a con‐
55                  current reader may see the result of none of them,  only  A,
56                  or both A and B. It cannot see the result of only B.
57
58                write_concurrency:
59                  This is an optimization to achieve very efficient concurrent
60                  add and sub operations at the expense of potential read  in‐
61                  consistency and memory consumption per counter.
62
63                  Read  operations  may  see sequentially inconsistent results
64                  with regard to concurrent write operations.  Even  if  write
65                  operation A is done sequentially before write operation B, a
66                  concurrent reader may see any combination of A  and  B,  in‐
67                  cluding  only  B. A read operation is only guaranteed to see
68                  all writes done sequentially before the read. No writes  are
69                  ever lost, but will eventually all be seen.
70
71                  The  typical  use case for write_concurrency is when concur‐
72                  rent calls to add and sub toward the same counters are  very
73                  frequent, while calls to get and put are much less frequent.
74                  The lack of absolute read consistency must also  be  accept‐
75                  able.
76
77              Counters  are  not tied to the current process and are automati‐
78              cally garbage collected when they are no longer referenced.
79
80       get(Ref, Ix) -> integer()
81
82              Types:
83
84                 Ref = counters_ref()
85                 Ix = integer()
86
87              Read counter value.
88
89       add(Ref, Ix, Incr) -> ok
90
91              Types:
92
93                 Ref = counters_ref()
94                 Ix = Incr = integer()
95
96              Add Incr to counter at index Ix.
97
98       sub(Ref, Ix, Decr) -> ok
99
100              Types:
101
102                 Ref = counters_ref()
103                 Ix = Decr = integer()
104
105              Subtract Decr from counter at index Ix.
106
107       put(Ref, Ix, Value) -> ok
108
109              Types:
110
111                 Ref = counters_ref()
112                 Ix = Value = integer()
113
114              Write Value to counter at index Ix.
115
116          Note:
117              Despite its name, the write_concurrency  optimization  does  not
118              improve  put. A call to put is a relatively heavy operation com‐
119              pared to the very lightweight and scalable add and sub. The cost
120              for  a put with write_concurrency is like a get plus a put with‐
121              out write_concurrency.
122
123
124       info(Ref) -> Info
125
126              Types:
127
128                 Ref = counters_ref()
129                 Info = #{size := Size, memory := Memory}
130                 Size = Memory = integer() >= 0
131
132              Return information about a counter array in a map. The  map  has
133              the following keys (at least):
134
135                size:
136                  The number of counters in the array.
137
138                memory:
139                  Approximate memory consumption for the array in bytes.
140
141
142
143Ericsson AB                       erts 12.1.5                      counters(3)
Impressum