View Source ringbuffer (ringbuffer v1.3.0)
Ringbuffer implements a length limited queue. In systems this is often implemented as a ring, or cylic, buffer. Where the writer can push the reader ahead if the buffer is full.
This kind of buffers is useful in situations where you can have surges of writers, with a limited amount of readers. And where it is allowed to drop entries from the queue if the readers can't keep up with the writers.
An example is a logging system for a http server, which can handle large bursts of requests. The logger is often limited in its throughput, and it is perfectly ok to drop log entries if that means that the server can handle the peak load.
This ring buffer is technically not a ring. It is a size limited buffer, implemented in ets. Its main characteristics are:
- Optimized for writes: non locking and non blocking queue writes;
- Size limited, define the maximum number of entries upon queue creation;
- Readers are synchronized to prevent race conditions;
- Readers return the number of entries that were lost due to too fast writers;
- As many queues as needed.
Summary
Functions
Delete a named ringbuffer, all queued data is destroyed. The ets table and the synchronizing process are deleted.
Create a new named buffer of Size entries. The name must be unique for all ets tables. The name must be an atom, and is used for the name of the ets table. A process owning the ets table and synchronizing the readers is added to <tt>ringbuffer_sup</tt>.
Read the next entry from the named ringbuffer. Return the number of skipped entries and the payload of the entry read. An entry is skipped if the readers are falling behind the writers by more that the size of the buffer. <tt>{error, empty}</tt> is returned if the buffer is empty.
Find the ringbuffer with a certain name, return the pid if found, otherwise undefined.
Add an entry to the named ringbuffer. Never fails, if the ringbuffer is full then older entries are overwritten.
Types
-type ringbuffer() :: term().
Functions
-spec delete(Name) -> ok | {error, not_found} when Name :: atom().
Delete a named ringbuffer, all queued data is destroyed. The ets table and the synchronizing process are deleted.
-spec new(Name, Size) -> {ok, pid()} | {error, Reason} when Name :: atom(), Size :: pos_integer(), Reason :: {already_started, pid()} | term().
Create a new named buffer of Size entries. The name must be unique for all ets tables. The name must be an atom, and is used for the name of the ets table. A process owning the ets table and synchronizing the readers is added to <tt>ringbuffer_sup</tt>.
-spec read(Name) -> {ok, {SkipCount, Payload}} | {error, empty} when Name :: atom(), SkipCount :: non_neg_integer(), Payload :: term().
Read the next entry from the named ringbuffer. Return the number of skipped entries and the payload of the entry read. An entry is skipped if the readers are falling behind the writers by more that the size of the buffer. <tt>{error, empty}</tt> is returned if the buffer is empty.
Find the ringbuffer with a certain name, return the pid if found, otherwise undefined.
Add an entry to the named ringbuffer. Never fails, if the ringbuffer is full then older entries are overwritten.