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

Blocking ring buffer consumer. More...

#include <ring_buffer>

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

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

Public Member Functions
	Ring_buffer_consumer (Status const &status, Slot const *slots)
	Construct ring buffer consumer.
State	peek (Item &item, Drop_policy policy, Sequence *drops=nullptr)
	Poll and possibly dequeue an item from the ring buffer.
size_t	dequeue (Item items[], size_t capacity, size_t burst, Drop_policy policy, Yield const &yield, Sequence *drops=nullptr)
	Dequeue items from the ring buffer.
Public Member Functions inherited from utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >
	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
Public Types inherited from utrace::Ring_buffer_consumer_raw< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >
enum class	Drop_policy { Conservative = 0 , Minimal }
	Item drop policy. More...
enum class	State
	Status of the dequeue operation.
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< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >

Blocking 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 510 of file ring_buffer.

Constructor & Destructor Documentation

Ring_buffer_consumer()

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

utrace::Ring_buffer_consumer< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >::Ring_buffer_consumer ( 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 535 of file ring_buffer.

Member Function Documentation

dequeue()

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

size_t utrace::Ring_buffer_consumer< SEQUENCE_TYPE, ITEM_TYPE, GENERATION_PTR >::dequeue ( Item items[], size_t capacity, size_t burst, Drop_policy policy, Yield const & yield, Sequence * drops = nullptr )

inline

Dequeue items from the ring buffer.

Dequeue multiple items from the ring buffer. The goal is to dequeue as many items as available from the ring buffer in a single call to avoid overhead. This operation blocks until at least burst items have been dequeued (but returns immediately if an item is dropped).

The implementation implicitly spins actively while waiting for items to be dequeued from the ring buffer. The yield function can implement passive waiting. Its argument is the number of idle spinning cycles that already happened and if the function returns true, this number is reset.

Parameters

[out]	items	Array to dequeue the next items from the ring buffer into (as copies).
	capacity	Capacity of items (in items).
	burst	Minimal number of items that should be collected before returning in case of waiting for items.
	policy	Item drop policy.
	yield	Yield function to implement passive waiting. Executed in every spinning cycle when no next item has been produced yet. Its argument is the current counter of the idle spinning cycles and that counter is reset when the function returns true.
[out]	drops	Pointer to store the number of items that have been dropped. Can be nullptr.

Returns

Number of items dequeued and stored into items.

Definition at line 595 of file ring_buffer.

peek()

template<typename SEQUENCE_TYPE, typename ITEM_TYPE, auto GENERATION_PTR>

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

inline

Poll and possibly dequeue an item from the ring buffer.

This operation never blocks. However, since the expected sequence counter of the next item is managed internally with mutual exclusion, multiple concurrent calls to this method might affect the latency.

Parameters

[out]	item	Reference to dequeue the next item from the ring buffer into (as a copy).
	policy	Item drop policy.
[out]	drops	Pointer to store the number of items that have been dropped. Can be nullptr.

Return values

State::Idle	No next item has been produced yet. No item has been dequeued, no item has been dropped.
State::Ready	A next item has been dequeued from the ring buffer and stored in 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).

Definition at line 560 of file ring_buffer.

Referenced by utrace::Ring_buffer_consumer< Sequence, Item, &Item::_number >::dequeue().

Here is the caller graph for this function:

---

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

• l4/utrace/ring_buffer