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
13       semantics:
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
61                  inconsistency 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,
67                  including 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 11.2                       counters(3)
Impressum