|
QuickCppLib 0.10
Eliminate all the tedious hassle when making state-of-the-art C++ 14 - 23 libraries!
|
Very fast threadsafe ring buffer log. More...
#include "ringbuffer_log.hpp"
Classes | |
| class | iterator_ |
| struct | unique_id |
| Used to tag an index as being an absolute lookup of a unique counter value returned by push_back/emplace_back. More... | |
Public Types | |
| using | container_type = typename Policy::container_type |
| using | value_type = typename container_type::value_type |
| The log record type. | |
| using | size_type = typename container_type::size_type |
| The size type. | |
| using | difference_type = typename container_type::difference_type |
| The difference type. | |
| using | reference = typename container_type::reference |
| The reference type. | |
| using | const_reference = typename container_type::const_reference |
| The const reference type. | |
| using | pointer = typename container_type::pointer |
| The pointer type. | |
| using | const_pointer = typename container_type::const_pointer |
| The const pointer type. | |
| using | iterator = iterator_<ringbuffer_log, pointer, reference> |
| The iterator type. | |
| using | const_iterator = iterator_<const ringbuffer_log, const_pointer, const_reference> |
| The const iterator type. | |
| using | reverse_iterator = std::reverse_iterator<iterator> |
| The reverse iterator type. | |
| using | const_reverse_iterator = std::reverse_iterator<const_iterator> |
| The const reverse iterator type. | |
Public Member Functions | |
| template<class... Args> | |
| ringbuffer_log (level starting_level, Args &&... args) noexcept(noexcept(container_type(std::forward< Args >(args)...))) | |
| Default construction, passes through args to container_type. | |
| ringbuffer_log (const ringbuffer_log &)=delete | |
| No copying. | |
| ringbuffer_log (ringbuffer_log &&)=delete | |
| No moving. | |
| ringbuffer_log & | operator= (const ringbuffer_log &)=delete |
| No copying. | |
| ringbuffer_log & | operator= (ringbuffer_log &&)=delete |
| No moving. | |
| void | swap (ringbuffer_log &o) noexcept |
| Swaps with another instance. | |
| level | log_level () const noexcept |
| THREADSAFE Returns the log level from the instance filtered by any LogLevelChecker. | |
| level | instance_log_level () const noexcept |
| THREADSAFE Returns the current per-instance log level. | |
| void | instance_log_level (level new_level) noexcept |
| THREADSAFE Sets the current per-instance log level. | |
| bool | empty () const noexcept |
| Returns true if the log is empty. | |
| size_type | size () const noexcept |
| Returns the number of items in the log. | |
| size_type | max_size () const noexcept |
| Returns the maximum number of items in the log. | |
| std::ostream * | immediate () const noexcept |
| Returns any std::ostream immediately printed to when a new log entry is added. | |
| void | immediate (std::ostream *s) noexcept |
| Set any std::ostream immediately printed to when a new log entry is added. | |
| bool | valid (unique_id id) const noexcept |
| True if a unique id is still valid. | |
| value_type | snapshot (size_type pos) const noexcept |
| Returns a tear-free copy of the record pos items from the newest, or a default constructed record if the ring does not hold that many. pos counts from the newest exactly as operator[](size_type) does. The accessors which hand back a reference into the ring (front(), back(), operator[], at() and the iterators) are racy by construction: a writer which wraps the ring can rewrite the very slot a reader is looking at, and no ordering prevents that. This copies the record out and discards the copy if the writer got to the slot first, so what it returns is always one whole record. | |
| bool | try_snapshot (size_type pos, value_type &out) const noexcept |
| Copies the record pos items from the newest into out, returning false if the ring does not hold that many records or if the writer overwrote the slot while it was being copied (in which case out is left unspecified). Unlike snapshot(), this never retries. | |
| value_type | snapshot_by_id (unique_id id) const noexcept |
| Returns a tear-free copy of the record with the given unique id, or a default constructed record if the ring no longer holds it. | |
| reference | front () noexcept |
| Returns the front of the ringbuffer. Be careful of races with concurrent modifies. | |
| const_reference | front () const noexcept |
| Returns the front of the ringbuffer. Be careful of races with concurrent modifies. | |
| reference | operator[] (size_type pos) noexcept |
| Returns a reference to the specified element. Be careful of races with concurrent modifies. | |
| reference | operator[] (unique_id id) noexcept |
| Returns a reference to the specified element. | |
| const_reference | operator[] (size_type pos) const noexcept |
| Returns a reference to the specified element. Be careful of races with concurrent modifies. | |
| const_reference | operator[] (unique_id id) const noexcept |
| Returns a reference to the specified element. | |
| reference | back () noexcept |
| Returns the back of the ringbuffer. Be careful of races with concurrent modifies. | |
| const_reference | back () const noexcept |
| Returns the back of the ringbuffer. Be careful of races with concurrent modifies. | |
| iterator | begin () noexcept |
| Returns an iterator to the first item in the log. Be careful of races with concurrent modifies. | |
| const_iterator | begin () const noexcept |
| Returns an iterator to the first item in the log. Be careful of races with concurrent modifies. | |
| const_iterator | cbegin () const noexcept |
| Returns an iterator to the first item in the log. Be careful of races with concurrent modifies. | |
| iterator | end () noexcept |
| Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies. | |
| const_iterator | end () const noexcept |
| Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies. | |
| const_iterator | cend () const noexcept |
| Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies. | |
| void | clear () noexcept |
| Clears the log. | |
| size_type | push_back (value_type &&v) noexcept |
| THREADSAFE Logs a new item, returning its unique counter id. | |
| template<class... Args> | |
| size_type | emplace_back (level __level, Args &&... args) noexcept |
| THREADSAFE Logs a new item, returning its unique counter id. | |
Static Public Attributes | |
| static constexpr size_t | max_items = Policy::max_items |
| The maximum items to store according to Policy::max_items. If zero, use container's size(). | |
Friends | |
| template<class Parent, class Pointer, class Reference> | |
| class | iterator_ |
Very fast threadsafe ring buffer log.
Works on the basis of an always incrementing atomic<size_t> which writes into the ring buffer at modulus of the ring buffer size. Items stored per log entry are defined by the Policy class' value_type. To log an item, call the QUICKCPPLIB_RINGBUFFERLOG_ITEM_* family of macros.
Be aware iteration, indexing etc. is most recent first, so log[0] is the most recently logged item. Use the reversed iterators if you don't want this.
Logging is wait-free and never locks: a writer allocates its record id with one atomic fetch_add on the counter, marks its slot with the per slot seqlock word, writes the record and marks the slot clean again. Nothing waits on anything else, so a writer cannot be delayed by a slow or descheduled peer. This is a write-heavy, read-light log, and the protocol is arranged accordingly: the writer allocates one id, stores two marker words and copies the record, with the cheapest fences which are sufficient; a reader which races a writer re-checks and retries, and a reader which cannot get a whole record gives up rather than making the writer wait. Anything which makes writing slower to make reading cheaper or tidier is the wrong trade here.
A record is published in the sense that matters to a reader when its slot holds it, not when its id was allocated: two writers can be mid-flight at once, and one may finish before the other, so an id below the counter is not a promise that the record is there yet. Readers therefore validate what they copy - the seqlock word must be even at both ends of the copy, and the copy must carry the id which was asked for - and give up after a bounded number of attempts, returning a default constructed record. This is what makes the tear-free accessors safe without a lock: a slot holding a previous wrap's record, or an id whose writer has not finished, fails the id check rather than being returned as data.
One precondition follows from the same reasoning, and it is the only one: no more writers may be inside a push at the same time than the ring has entries (max_items), because two writers whose ids differ by exactly the ring size share a slot and would interleave their seqlock updates. Threads which log into their own log (the usual arrangement) satisfy it trivially; a shared log needs fewer concurrent writers than it has entries, which for the default 256 entry debug ring is almost always true. clear() additionally assumes no writer is inside a push: it rewrites every slot, and a writer interleaving with that is a different question from the one seqlocks answer.
For simple_ringbuffer_log_policy, typical item logging times are:
with backtrace (windows): up to 33 microseconds.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::container_type = typename Policy::container_type |
The container used to store the logged records set by Policy::container_type. Must be a ContiguousContainer.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::value_type = typename container_type::value_type |
The log record type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::size_type = typename container_type::size_type |
The size type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::difference_type = typename container_type::difference_type |
The difference type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::reference = typename container_type::reference |
The reference type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_reference = typename container_type::const_reference |
The const reference type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::pointer = typename container_type::pointer |
The pointer type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_pointer = typename container_type::const_pointer |
The const pointer type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::iterator = iterator_<ringbuffer_log, pointer, reference> |
The iterator type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_iterator = iterator_<const ringbuffer_log, const_pointer, const_reference> |
The const iterator type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::reverse_iterator = std::reverse_iterator<iterator> |
The reverse iterator type.
| using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_reverse_iterator = std::reverse_iterator<const_iterator> |
The const reverse iterator type.
|
inlineexplicitnoexcept |
Default construction, passes through args to container_type.
|
delete |
No copying.
|
delete |
No moving.
|
delete |
No copying.
|
delete |
No moving.
|
inlinenoexcept |
Swaps with another instance.
No synchronisation, and none is possible: this exchanges what each slot means for both logs at once - the records, the counter which numbers them, the markers which say which record is in which slot, and the point a clear retired ids at. A writer or reader running concurrently would be observing a log whose identity changes underneath it mid-operation, and there is no ordering which makes that observation meaningful; the requirement is exclusive access to both logs, exactly as std::swap on any container which is not itself thread-safe. The relaxed marker exchange below is the consequence, not an oversight: nothing is being published to anyone, because nobody else may be looking.
The atomics are exchanged element-wise because a vector of atomics cannot be swapped as a whole and because the marker words belong with the records they describe - they are moved together with _store and _counter. The bounds check is defensive: the parameter type fixes the container type, so two logs of this instantiation always have the same slot count.
(As the open-work register records, this function cannot currently be instantiated at all: std::swap does not accept the atomic members.)
|
inlinenoexcept |
THREADSAFE Returns the log level from the instance filtered by any LogLevelChecker.
|
inlinenoexcept |
THREADSAFE Returns the current per-instance log level.
|
inlinenoexcept |
THREADSAFE Sets the current per-instance log level.
|
inlinenoexcept |
Returns true if the log is empty.
|
inlinenoexcept |
Returns the number of items in the log.
|
inlinenoexcept |
Returns the maximum number of items in the log.
|
inlinenoexcept |
Returns any std::ostream immediately printed to when a new log entry is added.
|
inlinenoexcept |
Set any std::ostream immediately printed to when a new log entry is added.
|
inlinenoexcept |
True if a unique id is still valid.
|
inlinenoexcept |
Returns a tear-free copy of the record pos items from the newest, or a default constructed record if the ring does not hold that many. pos counts from the newest exactly as operator[](size_type) does. The accessors which hand back a reference into the ring (front(), back(), operator[], at() and the iterators) are racy by construction: a writer which wraps the ring can rewrite the very slot a reader is looking at, and no ordering prevents that. This copies the record out and discards the copy if the writer got to the slot first, so what it returns is always one whole record.
|
inlinenoexcept |
Copies the record pos items from the newest into out, returning false if the ring does not hold that many records or if the writer overwrote the slot while it was being copied (in which case out is left unspecified). Unlike snapshot(), this never retries.
|
inlinenoexcept |
Returns a tear-free copy of the record with the given unique id, or a default constructed record if the ring no longer holds it.
|
inlinenoexcept |
Returns the front of the ringbuffer. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns the front of the ringbuffer. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns a reference to the specified element. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns a reference to the specified element.
|
inlinenoexcept |
Returns a reference to the specified element. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns a reference to the specified element.
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.
|
inlinenoexcept |
|
inlinenoexcept |
Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies.
|
inlinenoexcept |
Clears the log.
Rewrites every slot and retires every id issued so far.
Takes no lock and cannot take one without reintroducing the serialisation the class documentation rules out, so it assumes no writer is inside a push: a writer interleaving with the loop below shares a slot with it and the two would interleave their seqlock updates. Clearing a log concurrently with logging into it is a teardown/reset operation, not a logging operation; the per-slot marking is still worth doing, because it stops a reader accepting a slot mid-clear as a record, which is a different race and one this can close.
|
inlinenoexcept |
THREADSAFE Logs a new item, returning its unique counter id.
|
inlinenoexcept |
THREADSAFE Logs a new item, returning its unique counter id.
|
friend |
|
staticconstexpr |
The maximum items to store according to Policy::max_items. If zero, use container's size().