View Source exometer_slide (exometer_core v2.0.0)

Efficient sliding-window buffer

Initial implementation: 29 Sep 2009 by Tony Rogvall

This module implements an efficient sliding window, maintaining two lists - a primary and a secondary. Values are paired with a timestamp (millisecond resolution, see exometer_util:timestamp/0) and prepended to the primary list. When the time span between the oldest and the newest entry in the primary list exceeds the given window size, the primary list is shifted into the secondary list position, and the new entry is added to a new (empty) primary list.

The window can be converted to a list using to_list/1 or folded over using foldl/3.

Summary

Functions

Add an element to the buffer, tagging it with the current time.

Add an element to the buffer, tagged with the given timestamp.

Add an element to the buffer, optionally indicating if a swap occurred.

Fold over all values in the sliding window.

Fold over the sliding window, starting from Timestamp.

Create a new sliding-window buffer.

Callback function for exometer_histogram

Empty the buffer
Convert the sliding window into a list of timestamped values.

Types

-type cur_state() :: any().
-type fold_acc() :: any().
-type fold_fun() :: fun(({timestamp(), value()}, fold_acc()) -> fold_acc()).
-type sample_fun() :: fun((timestamp(), value(), cur_state()) -> cur_state()).
-type timestamp() :: exometer_util:timestamp().
-type transform_fun() :: fun((timestamp(), cur_state()) -> cur_state()).
-type value() :: any().

Functions

-spec add_element(value(), #slide{}) -> #slide{}.

Add an element to the buffer, tagging it with the current time.

Note that the buffer is a sliding window. Values will be discarded as they move out of the specified time span.
Link to this function

add_element(TS, Evt, Slide)

View Source
-spec add_element(timestamp(), value(), #slide{}) -> #slide{}.

Add an element to the buffer, tagged with the given timestamp.

Apart from the specified timestamp, this function works just like add_element/2.
Link to this function

add_element(TS, Evt, Slide, Wrap)

View Source
-spec add_element(timestamp(), value(), #slide{}, true) -> {boolean(), #slide{}};
           (timestamp(), value(), #slide{}, false) -> #slide{}.

Add an element to the buffer, optionally indicating if a swap occurred.

This function works like add_element/3, but will also indicate whether the sliding window buffer swapped lists (this means that the 'primary' buffer list became full and was swapped to 'secondary', starting over with an empty primary list. If Wrap == true, the return value will be {Bool,Slide}, where Bool==true means that a swap occurred, and Bool==false means that it didn't.

If Wrap == false, this function works exactly like add_element/3.

One possible use of the Wrap == true option could be to keep a sliding window buffer of values that are pushed e.g. to an external stats service. The swap indication could be a trigger point where values are pushed in order to not lose entries.
-spec foldl(fold_fun(), fold_acc(), #slide{}) -> fold_acc().

Fold over all values in the sliding window.

The fun should as fun({Timestamp, Value}, Acc) -> NewAcc. The values are processed in order from oldest to newest.
Link to this function

foldl(Timestamp, Fun, Acc, Slide)

View Source
-spec foldl(timestamp(), fold_fun(), fold_acc(), #slide{}) -> fold_acc().

Fold over the sliding window, starting from Timestamp.

The fun should as fun({Timestamp, Value}, Acc) -> NewAcc. The values are processed in order from oldest to newest.
-spec new(_Size :: integer(), _Options :: list()) -> #slide{}.

Create a new sliding-window buffer.

Size determines the size in milliseconds of the sliding window. The implementation prepends values into a primary list until the oldest element in the list is Size ms older than the current value. It then swaps the primary list into a secondary list, and starts prepending to a new primary list. This means that more data than fits inside the window will be kept - upwards of twice as much. On the other hand, updating the buffer is very cheap.
Link to this function

new(Size, Period, SampleFun, TransformFun, Opts)

View Source
-spec new(integer(), integer(), sample_fun(), transform_fun(), list()) -> #slide{}.

Callback function for exometer_histogram

This function is not intended to be used directly. The arguments _SampleFun and _TransformFun are ignored.
-spec reset(#slide{}) -> #slide{}.
Empty the buffer
-spec to_list(#slide{}) -> [{timestamp(), value()}].
Convert the sliding window into a list of timestamped values.