utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR > Class Template Reference

Polling ring buffer consumer. More...

#include <ring_buffer>

Inheritance diagram for utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >:

Collaboration diagram for utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >:

Public Types
enum class	Drop_policy { Conservative = 0 , Minimal }
	Item drop policy. More...
enum class	State
	Status of the dequeue operation.

Public Member Functions
	Ring_buffer_consumer_raw (Status const &status, Slot const *slots)
	Construct ring buffer consumer.
size_t	items () const
	Get the number of items.
State	peek (Item &item, Drop_policy policy, Sequence &current, Sequence *drops=nullptr) const
	Poll and possibly dequeue an item from the ring buffer.

Additional Inherited Members
Static Public Member Functions inherited from utrace::Ring_buffer< SEQUENCE_TYPE >
static void	check_items (size_t const items)
	Check that the number of items is a power of two.
static void	check_mask (size_t const mask)
	Check that the item mask is a power of two minus one.
Static Public Attributes inherited from utrace::Ring_buffer< SEQUENCE_TYPE >
static constexpr Sequence const	nil = 0U
	Invalid (non-committed) items set their sequence counter to 0.

Detailed Description

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>
class utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >

Polling ring buffer consumer.

Both the ring buffer status area and ring buffer slots are accessed in a read-only fashion.

Template Parameters

SEQUENCE_TYPE	Numerical type for storing sequence and generation counters. Must be suitable for atomic access.
ITEM_TYPE	Actual ring buffer item type.
GENERATION_PTR	Class member pointer to the member that contains the sequence number within the item. The member needs to be suitable for an atomic reference.

Definition at line 334 of file ring_buffer.

Member Enumeration Documentation

Drop_policy

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

enum class utrace::Ring_buffer_consumer_raw::Drop_policy

strong

Item drop policy.

This affects the behavior of the consumer when an item drop is detected (i.e. the consumer loses access to an item or multiple items in the ring buffer that have been overwritten by a producer in the meantime).

Enumerator
Conservative	Conservative item drop policy. Continue with the newest item in the ring buffer (i.e. proactively drop all the items except the newest one). This policy is suitable when the production of items is always faster than the consumption and it gives the consumer a chance to dequeue at least some items from the ring buffer before it falls behind again.
Minimal	Minimal item drop policy. Continue with the oldest item in the ring buffer (i.e. do not proactively drop more items than those that have been lost already). This policy is suitable when the production of items is mostly slower than the consumption and the consumer is able to catch up after an occasional drop of items.

Definition at line 353 of file ring_buffer.

Constructor & Destructor Documentation

Ring_buffer_consumer_raw()

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >::Ring_buffer_consumer_raw ( Status const & status, Slot const * slots )

inline

Construct ring buffer consumer.

Parameters

status	Ring buffer status area.
slots	Ring buffer slots.

Exceptions

td::length_error

If the item mask (in the ring buffer status area) is not a power of two minus one.

Definition at line 394 of file ring_buffer.

Member Function Documentation

peek()

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

State utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >::peek ( Item & item, Drop_policy policy, Sequence & current, Sequence * drops = nullptr ) const

inline

Poll and possibly dequeue an item from the ring buffer.

This operation never blocks.

Parameters

[out]	item	Reference to dequeue the next item from the ring buffer into (as a copy).
	policy	Item drop policy.
[in,out]	current	Sequence counter of the next item to be dequeued from the ring buffer. Initialize to Ring_buffer::nil to get the sequence counter of the oldest or the newest item currently available in the ring buffer (depending on the item drop policy).
[out]	drops	Pointer to store the number of items that have been dropped. Can be nullptr.

Return values

State::Idle	The next item with the expected sequence counter has not been produced yet. No item has been dequeued, no item has been dropped, the sequence counter is unchanged.
State::Ready	The next item (with the expected sequence counter) has been dequeued from the ring buffer and stored in item. The sequence counter current has been advanced to the next expected item. No item has been dropped.
State::Drop	Some items have been dropped (missed). No item has been dequeued. The number of dropped items has been stored to drops (if non-nullptr). The sequence counter current has been advanced to the oldest (if the drop policy is Minimal) or to the newest (if the drop policy is Conservative), respectively.

Definition at line 435 of file ring_buffer.

---

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

• l4/utrace/ring_buffer