1counters(3) Erlang Module Definition counters(3)
2
6 counters - Counter Functions
7
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 * Counters are 64 bit signed integers.
16 * Counters wrap around at overflow and underflow operations.
18 * Counters are initialized to zero and can then only be written to by
20 adding or subtracting.
21 * Write operations guarantee atomicity. No intermediate results can
23 be seen from a single write operation.
24 * Two types of counter arrays can be created with options atomics or
26 write_concurrency. The atomics counters have good allround perfor‐
27 mance with nice consistent semantics while write_concurrency coun‐
28 ters offers even better concurrent write performance at the expense
29 of some potential read inconsistencies. See new/2.
30 * Indexes into counter arrays are one-based. A counter array of size
32 N contains N counters with index from 1 to N.
33
35 counters_ref()
36 Identifies a counter array returned from new/2.
38
40 new(Size, Opts) -> counters_ref()
41 Types:
43 Size = integer() >= 1
45 Opts = [Opt]
46 Opt = atomics | write_concurrency
47 Create a new counter array of Size counters.
49 Argument Opts is a list of the following possible options:
51 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 none of them, only A, or both A and
56 B. It cannot see only B.
57 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 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 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 Counters are not tied to the current process and are automati‐
78 cally garbage collected when they are no longer referenced.
79 get(Ref, Ix) -> integer()
81 Types:
83 Ref = counters_ref()
85 Ix = integer()
86 Read counter value.
88 add(Ref, Ix, Incr) -> ok
90 Types:
92 Ref = counters_ref()
94 Ix = Incr = integer()
95 Add Incr to counter at index Ix.
97 sub(Ref, Ix, Decr) -> ok
99 Types:
101 Ref = counters_ref()
103 Ix = Decr = integer()
104 Subtract Decr from counter at index Ix.
106 put(Ref, Ix, Value) -> ok
108 Types:
110 Ref = counters_ref()
112 Ix = Value = integer()
113 Write Value to counter at index Ix.
115 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 info(Ref) -> Info
125 Types:
127 Ref = counters_ref()
129 Info = #{size := Size, memory := Memory}
130 Size = Memory = integer() >= 0
131 Return information about a counter array in a map. The map has
133 the following keys (at least):
134 size:
136 The number of counters in the array.
137 memory:
139 Approximate memory consumption for the array in bytes.
140Ericsson AB erts 10.5.6 counters(3)