From fefb5d039e87ff7137e78b3d5f2eaf01e498ec4d Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Tue, 25 Sep 2018 13:34:52 +0200 Subject: erts: Add new module 'counters' --- erts/doc/src/counters.xml | 142 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 erts/doc/src/counters.xml (limited to 'erts/doc/src/counters.xml') diff --git a/erts/doc/src/counters.xml b/erts/doc/src/counters.xml new file mode 100644 index 0000000000..85eedfdadc --- /dev/null +++ b/erts/doc/src/counters.xml @@ -0,0 +1,142 @@ + + + + +
+ + 2018 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + counters +
+ counters + Counter Functions + +

This module provides a set of functions to do operations towards + shared mutable counter variables. The implementation does not utilize any + software level locking, which makes it very efficient for concurrent + access. The counters are organized into arrays with the follwing + semantics:

+ + +

Counters are 64 bit signed integers.

+ + +

Counters wrap around at overflow and underflow operations.

+ +

Counters are initialized to zero and can then only be written to + by adding or subtracting.

+ + +

Write operations guarantee atomicity. No intermediate results can be + seen from a single write operation.

+ + +

Two types of counter arrays can be created with options atomics or + write_concurrency. The atomics counters have good allround + performance with nice consistent semantics while + write_concurrency counters offers even better concurrent + write performance at the expense of some potential read + inconsistencies. See new/2.

+ + +

Indexes into counter arrays are one-based. A counter array of + size N contains N counters with index from 1 to N.

+ + + + + + + +

Identifies a counter array returned from + new/2.

+ + + + + + + + Create counter array + +

Create a new counter array of Size counters.

+

Argument Opts is a list of the following possible + options:

+ + atomics (Default) +

Counters will be sequentially consistent. If write + operation A is done sequencially before write operation B, then a concurrent reader + may see none of them, only A, or both A and B. It cannot see only B.

+ + write_concurrency +

This is an optimization to achieve very efficient concurrent + write operations at the expense of potential read inconsistency and memory + consumption per counter.

+

Read operations may see sequentially inconsistent results with + regard to concurrent write operations. Even if write operation A is done + sequencially before write operation B, a concurrent reader may see any + combination of A and B, including only B. A read operation is only + guaranteed to see all writes done sequentially before the read. No writes + are ever lost, but will eventually all be seen.

+ + + + + + + + Read counter value + +

Read counter value.

+ + + + + + Add to counter + +

Add Incr to counter.

+ + + + + + Subtract from counter + +

Subtract Decr from counter.

+ + + + + + Get information about counter array. + +

Return information about a counter array in a map. The map + has the following keys (at least):

+ + size +

The number of counters in the array.

 + memory +

Approximate memory consumption for the array in + bytes.

 + + + + + + -- cgit v1.2.3