| Overview |  |
Copyright © 2021 Marc Worrell
Authors: Marc Worrell (marc@worrell.nl).
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:
ringbuffer() = term()
| delete/1 | Delete a named ringbuffer, all queued data is destroyed. |
| new/2 | Create a new named buffer of Size entries. |
| read/1 | Read the next entry from the named ringbuffer. |
| start/0 | |
| write/2 | Add an entry to the named ringbuffer. |
delete(Name::atom()) -> ok | {error, not_found}
Delete a named ringbuffer, all queued data is destroyed. The ets table and the synchronizing process are deleted.
new(Name::atom(), Size::pos_integer()) -> {ok, pid()} | {error, 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 ringbuffer_sup.
read(Name::atom()) -> {ok, {non_neg_integer(), term()}} | {error, empty}
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. {error, empty} is returned if the buffer is empty.
start() -> any()
write(Name::atom(), Payload::term()) -> ok
Add an entry to the named ringbuffer. Never fails, if the ringbuffer is full then older entries are overwritten.
Generated by EDoc