QuickCppLib 0.10
Eliminate all the tedious hassle when making state-of-the-art C++ 14 - 23 libraries!
Loading...
Searching...
No Matches
quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker > Class Template Reference

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_

Detailed Description

template<class Policy, class LogLevelChecker>
class quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >

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:

  • without backtrace: 1.2 microseconds.
  • with backtrace (windows): up to 33 microseconds.

    Todo
    Implement STL allocator for a memory mapped file on disc so log survives sudden process exit.

Member Typedef Documentation

◆ container_type

template<class Policy, class LogLevelChecker>
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.

◆ value_type

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::value_type = typename container_type::value_type

The log record type.

◆ size_type

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::size_type = typename container_type::size_type

The size type.

◆ difference_type

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::difference_type = typename container_type::difference_type

The difference type.

◆ reference

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::reference = typename container_type::reference

The reference type.

◆ const_reference

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_reference = typename container_type::const_reference

The const reference type.

◆ pointer

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::pointer = typename container_type::pointer

The pointer type.

◆ const_pointer

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_pointer = typename container_type::const_pointer

The const pointer type.

◆ iterator

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::iterator = iterator_<ringbuffer_log, pointer, reference>

The iterator type.

◆ const_iterator

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_iterator = iterator_<const ringbuffer_log, const_pointer, const_reference>

The const iterator type.

◆ reverse_iterator

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::reverse_iterator = std::reverse_iterator<iterator>

The reverse iterator type.

◆ const_reverse_iterator

template<class Policy, class LogLevelChecker>
using quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::const_reverse_iterator = std::reverse_iterator<const_iterator>

The const reverse iterator type.

Constructor & Destructor Documentation

◆ ringbuffer_log() [1/3]

template<class Policy, class LogLevelChecker>
template<class... Args>
quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::ringbuffer_log ( level starting_level,
Args &&... args )
inlineexplicitnoexcept

Default construction, passes through args to container_type.

963 : _store(std::forward<Args>(args)...)
964 , _instance_level(starting_level)
965 , _counter(0)
966 , _immediate(nullptr)
967 , _cleared_at(0)
968 , _seq(_slots())
969 {
970 }
Very fast threadsafe ring buffer log.
Definition ringbuffer_log.hpp:604

◆ ringbuffer_log() [2/3]

template<class Policy, class LogLevelChecker>
quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::ringbuffer_log ( const ringbuffer_log< Policy, LogLevelChecker > & )
delete

No copying.

◆ ringbuffer_log() [3/3]

template<class Policy, class LogLevelChecker>
quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::ringbuffer_log ( ringbuffer_log< Policy, LogLevelChecker > && )
delete

No moving.

Member Function Documentation

◆ operator=() [1/2]

template<class Policy, class LogLevelChecker>
ringbuffer_log & quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator= ( const ringbuffer_log< Policy, LogLevelChecker > & )
delete

No copying.

◆ operator=() [2/2]

template<class Policy, class LogLevelChecker>
ringbuffer_log & quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator= ( ringbuffer_log< Policy, LogLevelChecker > && )
delete

No moving.

◆ swap()

template<class Policy, class LogLevelChecker>
void quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::swap ( ringbuffer_log< Policy, LogLevelChecker > & o)
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.)

1001 {
1002 std::swap(_store, o._store);
1003 auto t = o._instance_level.load(std::memory_order_relaxed);
1004 o._instance_level.store(_instance_level.load(std::memory_order_relaxed), std::memory_order_relaxed);
1005 _instance_level.store(t, std::memory_order_relaxed);
1006 std::swap(_counter, o._counter);
1007 std::swap(_cleared_at, o._cleared_at);
1008 std::swap(_immediate, o._immediate);
1009 // A vector of atomics cannot itself be swapped, and the sequence words
1010 // belong with the records they describe, so exchange them element-wise.
1011 const size_type n = _seq.size() < o._seq.size() ? _seq.size() : o._seq.size();
1012 for(size_type i = 0; i < n; i++)
1013 {
1014 const uint64_t a = _seq[i].load(std::memory_order_relaxed);
1015 const uint64_t b = o._seq[i].load(std::memory_order_relaxed);
1016 _seq[i].store(b, std::memory_order_relaxed);
1017 o._seq[i].store(a, std::memory_order_relaxed);
1018 }
1019 }
typename container_type::size_type size_type
The size type.
Definition ringbuffer_log.hpp:618
size_type size() const noexcept
Returns the number of items in the log.
Definition ringbuffer_log.hpp:1031

◆ log_level()

template<class Policy, class LogLevelChecker>
level quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::log_level ( ) const
inlinenoexcept

THREADSAFE Returns the log level from the instance filtered by any LogLevelChecker.

1022{ return LogLevelChecker()(instance_log_level()); }
level instance_log_level() const noexcept
THREADSAFE Returns the current per-instance log level.
Definition ringbuffer_log.hpp:1024

◆ instance_log_level() [1/2]

template<class Policy, class LogLevelChecker>
level quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::instance_log_level ( ) const
inlinenoexcept

THREADSAFE Returns the current per-instance log level.

1024{ return _instance_level.load(std::memory_order_relaxed); }

◆ instance_log_level() [2/2]

template<class Policy, class LogLevelChecker>
void quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::instance_log_level ( level new_level)
inlinenoexcept

THREADSAFE Sets the current per-instance log level.

1026{ _instance_level.store(new_level, std::memory_order_relaxed); }

◆ empty()

template<class Policy, class LogLevelChecker>
bool quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::empty ( ) const
inlinenoexcept

Returns true if the log is empty.

1029{ return size() == 0; }

◆ size()

template<class Policy, class LogLevelChecker>
size_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::size ( ) const
inlinenoexcept

Returns the number of items in the log.

1031{ return _live_size(_counter.load(std::memory_order_acquire)); }

◆ max_size()

template<class Policy, class LogLevelChecker>
size_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::max_size ( ) const
inlinenoexcept

Returns the maximum number of items in the log.

1033{ return max_items ? max_items : _store.size(); }
static constexpr size_t max_items
The maximum items to store according to Policy::max_items. If zero, use container's size().
Definition ringbuffer_log.hpp:613

◆ immediate() [1/2]

template<class Policy, class LogLevelChecker>
std::ostream * quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::immediate ( ) const
inlinenoexcept

Returns any std::ostream immediately printed to when a new log entry is added.

1035{ return _immediate; }

◆ immediate() [2/2]

template<class Policy, class LogLevelChecker>
void quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::immediate ( std::ostream * s)
inlinenoexcept

Set any std::ostream immediately printed to when a new log entry is added.

1037{ _immediate = s; }

◆ valid()

template<class Policy, class LogLevelChecker>
bool quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::valid ( unique_id id) const
inlinenoexcept

True if a unique id is still valid.

1050 {
1051 const size_type counter = _counter.load(std::memory_order_acquire);
1052 const size_type cleared = _cleared_at.load(std::memory_order_acquire);
1053 return id.value < counter && id.value >= cleared && (counter - id.value) <= _slots();
1054 }

◆ snapshot()

template<class Policy, class LogLevelChecker>
value_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::snapshot ( size_type pos) const
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.

1065 {
1067 // The ring holds at most `held` records, so a request from beyond that can
1068 // never be satisfied. Asking _try_snapshot_counter for it used to loop
1069 // forever: the counter-based liveness test rejects exactly pos >= held, so
1070 // snapshot(size()) - and snapshot(size()-1) once the ring had wrapped -
1071 // spun with no escape, in a const noexcept accessor documented as
1072 // returning a default constructed record in that case. The attempt bound
1073 // covers the other end: a writer that keeps overwriting the requested slot
1074 // must make the reader give up, not livelock.
1075 // One named local and one return statement, so that the compiler can elide
1076 // the copy out of it: with two return statements clang declines the
1077 // elision and emits two 256 byte memcpy calls - one out of the ring into
1078 // this object, one into the caller's - where g++ inlines both. Same source,
1079 // 3 ns against 21 ns.
1080 bool found = false;
1081 for(size_t attempt = 0; attempt < SNAPSHOT_ATTEMPTS; attempt++)
1082 {
1083 const size_type counted = _counter.load(std::memory_order_acquire);
1084 if(pos >= _live_size(counted))
1085 {
1086 break;
1087 }
1088 if(_try_snapshot_counter(counted - 1 - pos, ret))
1089 {
1090 found = true;
1091 break;
1092 }
1094 }
1095 if(!found)
1096 {
1097 ret = value_type();
1098 }
1099 return ret;
1100 }
typename container_type::value_type value_type
The log record type.
Definition ringbuffer_log.hpp:616

◆ try_snapshot()

template<class Policy, class LogLevelChecker>
bool quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::try_snapshot ( size_type pos,
value_type & out ) const
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.

1106 {
1107 const size_type counted = _counter.load(std::memory_order_acquire);
1108 return pos < _live_size(counted) && _try_snapshot_counter(counted - 1 - pos, out);
1109 }

◆ snapshot_by_id()

template<class Policy, class LogLevelChecker>
value_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::snapshot_by_id ( unique_id id) const
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.

1114 {
1116 // As snapshot(): one named local, one return, so the copy can be elided.
1117 bool found = false;
1118 for(size_t attempt = 0; attempt < SNAPSHOT_ATTEMPTS; attempt++)
1119 {
1120 const size_type counted = _counter.load(std::memory_order_acquire);
1121 if(id.value >= counted || (counted - id.value) > _slots() ||
1122 id.value < _cleared_at.load(std::memory_order_acquire))
1123 {
1124 break;
1125 }
1126 if(_try_snapshot_counter(id.value, ret))
1127 {
1128 found = true;
1129 break;
1130 }
1132 }
1133 if(!found)
1134 {
1135 ret = value_type();
1136 }
1137 return ret;
1138 }

◆ front() [1/2]

template<class Policy, class LogLevelChecker>
reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::front ( )
inlinenoexcept

Returns the front of the ringbuffer. Be careful of races with concurrent modifies.

1140{ return _store[_counter_to_idx(_counter.load(std::memory_order_acquire) - 1)]; }

◆ front() [2/2]

template<class Policy, class LogLevelChecker>
const_reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::front ( ) const
inlinenoexcept

Returns the front of the ringbuffer. Be careful of races with concurrent modifies.

1142{ return _store[_counter_to_idx(_counter.load(std::memory_order_acquire) - 1)]; }

◆ operator[]() [1/4]

template<class Policy, class LogLevelChecker>
reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator[] ( size_type pos)
inlinenoexcept

Returns a reference to the specified element. Be careful of races with concurrent modifies.

1174{ return _store[_counter_to_idx(_counter.load(std::memory_order_acquire) - 1 - pos)]; }

◆ operator[]() [2/4]

template<class Policy, class LogLevelChecker>
reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator[] ( unique_id id)
inlinenoexcept

Returns a reference to the specified element.

1176{ return _store[_counter_to_idx(id.value)]; }

◆ operator[]() [3/4]

template<class Policy, class LogLevelChecker>
const_reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator[] ( size_type pos) const
inlinenoexcept

Returns a reference to the specified element. Be careful of races with concurrent modifies.

1178{ return _store[_counter_to_idx(_counter.load(std::memory_order_acquire) - 1 - pos)]; }

◆ operator[]() [4/4]

template<class Policy, class LogLevelChecker>
const_reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::operator[] ( unique_id id) const
inlinenoexcept

Returns a reference to the specified element.

1180{ return _store[_counter_to_idx(id.value)]; }

◆ back() [1/2]

template<class Policy, class LogLevelChecker>
reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::back ( )
inlinenoexcept

Returns the back of the ringbuffer. Be careful of races with concurrent modifies.

1183 {
1184 const size_type counter = _counter.load(std::memory_order_acquire);
1185 const size_type size = _live_size(counter);
1186 return _store[_counter_to_idx(counter - size)];
1187 }

◆ back() [2/2]

template<class Policy, class LogLevelChecker>
const_reference quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::back ( ) const
inlinenoexcept

Returns the back of the ringbuffer. Be careful of races with concurrent modifies.

1190 {
1191 const size_type counter = _counter.load(std::memory_order_acquire);
1192 const size_type size = _live_size(counter);
1193 return _store[_counter_to_idx(counter - size)];
1194 }

◆ begin() [1/2]

template<class Policy, class LogLevelChecker>
iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::begin ( )
inlinenoexcept

Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.

1198 {
1199 const size_type counter = _counter.load(std::memory_order_acquire);
1200 const size_type size = _live_size(counter);
1201 return iterator(this, counter - 1, size);
1202 }
iterator_< ringbuffer_log, pointer, reference > iterator
The iterator type.
Definition ringbuffer_log.hpp:802

◆ begin() [2/2]

template<class Policy, class LogLevelChecker>
const_iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::begin ( ) const
inlinenoexcept

Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.

1205 {
1206 const size_type counter = _counter.load(std::memory_order_acquire);
1207 const size_type size = _live_size(counter);
1208 return const_iterator(this, counter - 1, size);
1209 }
iterator_< const ringbuffer_log, const_pointer, const_reference > const_iterator
The const iterator type.
Definition ringbuffer_log.hpp:804

◆ cbegin()

template<class Policy, class LogLevelChecker>
const_iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::cbegin ( ) const
inlinenoexcept

Returns an iterator to the first item in the log. Be careful of races with concurrent modifies.

1212 {
1213 const size_type counter = _counter.load(std::memory_order_acquire);
1214 const size_type size = _live_size(counter);
1215 return const_iterator(this, counter - 1, size);
1216 }

◆ end() [1/2]

template<class Policy, class LogLevelChecker>
iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::end ( )
inlinenoexcept

Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies.

1219 {
1220 const size_type counter = _counter.load(std::memory_order_acquire);
1221 const size_type size = _live_size(counter);
1222 return iterator(this, counter - 1 - size, 0);
1223 }

◆ end() [2/2]

template<class Policy, class LogLevelChecker>
const_iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::end ( ) const
inlinenoexcept

Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies.

1226 {
1227 const size_type counter = _counter.load(std::memory_order_acquire);
1228 const size_type size = _live_size(counter);
1229 return const_iterator(this, counter - 1 - size, 0);
1230 }

◆ cend()

template<class Policy, class LogLevelChecker>
const_iterator quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::cend ( ) const
inlinenoexcept

Returns an iterator to the item after the last in the log. Be careful of races with concurrent modifies.

1233 {
1234 const size_type counter = _counter.load(std::memory_order_acquire);
1235 const size_type size = _live_size(counter);
1236 return const_iterator(this, counter - 1 - size, 0);
1237 }

◆ clear()

template<class Policy, class LogLevelChecker>
void quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::clear ( )
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.

1251 {
1252 // Clearing rewrites every slot, so it takes the same dirty/clean marking a
1253 // writer does: without it a reader could accept a slot mid-clear as a
1254 // record, exactly as it could mid-write.
1255 for(size_type i = 0; i < _store.size(); i++)
1256 {
1257 const size_type idx = i % _slots();
1258 // A marker no record can produce: 0 is neither `_seq_dirty(id)` nor
1259 // `_seq_clean(id)` for any id (those are 1 and 2 at the smallest), so a
1260 // reader rejects the slot instead of copying a cleared one.
1261 _seq[idx].store(0, std::memory_order_relaxed);
1263 _store[i] = value_type();
1264 }
1265 // Retire everything pushed so far rather than resetting the counter: a
1266 // reset made ids issued before the clear name whatever record now occupies
1267 // that slot, i.e. silently resolve to someone else's data.
1268 _cleared_at.store(_counter.load(std::memory_order_acquire), std::memory_order_release);
1269 }

◆ push_back()

template<class Policy, class LogLevelChecker>
size_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::push_back ( value_type && v)
inlinenoexcept

THREADSAFE Logs a new item, returning its unique counter id.

1272 {
1273 if(static_cast<level>(v.level) <= log_level())
1274 {
1275 if(_immediate)
1276 *_immediate << v << std::endl;
1277 // One atomic read-modify-write allocates the record's id, so concurrent
1278 // writers never take the same one and nothing has to serialise them; the
1279 // counter is *not* a completed-record watermark, because this writer may
1280 // finish after a writer with a larger id. A reader sorts that out per
1281 // record, with the seqlock plus the id the record carries - see the class
1282 // documentation and _try_snapshot_counter.
1283 size_type thisitem = _counter.fetch_add(1, std::memory_order_relaxed);
1284 v.counter = thisitem;
1285 const size_type idx = _counter_to_idx(thisitem);
1286 // Mark the slot dirty, fence, write the record, mark it clean - the fence
1287 // immediately before what it orders. See the note above
1288 // _try_snapshot_counter for why each half is the shape it is.
1289 _seq[idx].store(_seq_dirty(thisitem), std::memory_order_relaxed);
1291 _store[idx] = std::move(v);
1292 _seq[idx].store(_seq_clean(thisitem), std::memory_order_release);
1293 return thisitem;
1294 }
1295 return (size_type) -1;
1296 }
level log_level() const noexcept
THREADSAFE Returns the log level from the instance filtered by any LogLevelChecker.
Definition ringbuffer_log.hpp:1022

◆ emplace_back()

template<class Policy, class LogLevelChecker>
template<class... Args>
size_type quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::emplace_back ( level __level,
Args &&... args )
inlinenoexcept

THREADSAFE Logs a new item, returning its unique counter id.

1299 {
1300 if(__level <= log_level())
1301 {
1303 if(_immediate)
1304 *_immediate << v << std::endl;
1305 // As push_back: one fetch_add for the id, nothing waiting on another, and
1306 // the same marker/fence/record/marker sequence written out in place.
1307 size_type thisitem = _counter.fetch_add(1, std::memory_order_relaxed);
1308 v.counter = thisitem;
1309 const size_type idx = _counter_to_idx(thisitem);
1310 _seq[idx].store(_seq_dirty(thisitem), std::memory_order_relaxed);
1312 _store[idx] = std::move(v);
1313 _seq[idx].store(_seq_clean(thisitem), std::memory_order_release);
1314 return thisitem;
1315 }
1316 return (size_type) -1;
1317 }

◆ iterator_

template<class Policy, class LogLevelChecker>
template<class Parent, class Pointer, class Reference>
friend class iterator_
friend

Member Data Documentation

◆ max_items

template<class Policy, class LogLevelChecker>
size_t quickcpplib::_xxx::ringbuffer_log::ringbuffer_log< Policy, LogLevelChecker >::max_items = Policy::max_items
staticconstexpr

The maximum items to store according to Policy::max_items. If zero, use container's size().


The documentation for this class was generated from the following file: