A queue-based index matcher that pairs elements from two asynchronous streams by their index. More...

Classes
struct	NodeA
	Internal node storing an A-stream element and its associated index. More...
struct	NodeB
	Internal node storing a B-stream element and its associated index. More...

Public Types
using	A = t_a
	Alias for the first element type.
using	B = t_b
	Alias for the second element type.
using	Index = t_index
	Alias for the index type.
using	OnMatchFn = std::function<void(const A&, const B&)>
	Callback type invoked when indices match exactly.
using	OnNearMatchFn = std::function<void(const A&, const B&)>
	Callback type invoked when indices are within the distance tolerance.
using	UIndex = std::make_unsigned_t<Index>
	Unsigned version of the index type for circular arithmetic.

Public Member Functions
	IndexMatchQueue ()=default
	Default constructor.
	IndexMatchQueue (OnMatchFn on_match, OnNearMatchFn on_near_match={})
	Constructs the queue with match callbacks.
void	clear ()
	Clears both internal queues, discarding all pending elements.
void	pushA (Index idx, A a)
	Pushes an element into the A stream with the given index.
void	pushB (Index idx, B b)
	Pushes an element into the B stream with the given index.
void	setOnMatch (OnMatchFn on_match)
	Sets the callback for exact index matches.
void	setOnNearMatch (OnNearMatchFn on_near_match)
	Sets the callback for near index matches.

Protected Member Functions
void	drain ()
	Processes the front of both queues, invoking callbacks for matched or near-matched pairs.

Static Protected Member Functions
static constexpr UIndex	circularDistance (Index a, Index b) noexcept
	Computes the minimum circular distance between two indices.
static constexpr UIndex	HalfRange () noexcept
	Computes half the total range of the unsigned index type.
static constexpr bool	seqLess (Index a, Index b) noexcept
	Determines whether index a precedes index b in circular sequence order.

Detailed Description

template<class t_a, class t_b, class t_index = uint04>
class IndexMatchQueue< t_a, t_b, t_index >

A queue-based index matcher that pairs elements from two asynchronous streams by their index.

Elements of type A and type B are pushed independently with associated indices. When indices match exactly, the on-match callback is invoked. When indices are close within a configurable tolerance, the on-near-match callback is invoked instead. Stale entries are automatically discarded using circular sequence comparison to handle index wrapping.

Template Parameters

t_a	The type of elements in the first stream.
t_b	The type of elements in the second stream.
t_index	The integral index type used for matching, defaults to uint04.

Definition at line 27 of file IndexMatchQueue.h.

Constructor & Destructor Documentation

◆ IndexMatchQueue()

template<class t_a, class t_b, class t_index = uint04>

IndexMatchQueue< t_a, t_b, t_index >::IndexMatchQueue	(	OnMatchFn	on_match,
		OnNearMatchFn	on_near_match = {} )

inline

Constructs the queue with match callbacks.

Parameters

[in]	on_match	Callback invoked when an exact index match is found.
[in]	on_near_match	Optional callback invoked when a near index match is found within tolerance.

Definition at line 48 of file IndexMatchQueue.h.

Member Function Documentation

◆ circularDistance()

template<class t_a, class t_b, class t_index = uint04>

constexpr UIndex IndexMatchQueue< t_a, t_b, t_index >::circularDistance	(	Index	a,
		Index	b )

inlinestaticconstexprprotectednoexcept

Computes the minimum circular distance between two indices.

Parameters

[in]	a	The first index.
[in]	b	The second index.

Returns: The shortest unsigned distance between a and b in the circular index space.

Definition at line 173 of file IndexMatchQueue.h.

Referenced by drain().

◆ drain()

template<class t_a, class t_b, class t_index = uint04>

void IndexMatchQueue< t_a, t_b, t_index >::drain ( )

inlineprotected

Processes the front of both queues, invoking callbacks for matched or near-matched pairs.

Exact index matches trigger the on-match callback. When the B stream is ahead and the circular distance is within tolerance, the on-near-match callback is invoked. Stale entries that can no longer produce matches are discarded.

Definition at line 189 of file IndexMatchQueue.h.

References circularDistance(), and seqLess().

Referenced by pushA(), and pushB().

◆ HalfRange()

template<class t_a, class t_b, class t_index = uint04>

constexpr UIndex IndexMatchQueue< t_a, t_b, t_index >::HalfRange ( )

inlinestaticconstexprprotectednoexcept

Computes half the total range of the unsigned index type.

Used as the threshold for circular sequence comparison to handle index wrapping.

Returns: Half of the maximum representable unsigned index value plus one.

Definition at line 148 of file IndexMatchQueue.h.

Referenced by pushA(), pushB(), and seqLess().

◆ pushA()

template<class t_a, class t_b, class t_index = uint04>

void IndexMatchQueue< t_a, t_b, t_index >::pushA	(	Index	idx,
		A	a )

inline

Pushes an element into the A stream with the given index.

If the last element in the A queue has the same index, its value is updated in place. Otherwise the element is appended and drain is called to process any new matches. The queue is trimmed if it exceeds half the index range.

Parameters

[in]	idx	The index associated with this element.
[in]	a	The element value to push.

Definition at line 89 of file IndexMatchQueue.h.

References drain(), and HalfRange().

◆ pushB()

template<class t_a, class t_b, class t_index = uint04>

void IndexMatchQueue< t_a, t_b, t_index >::pushB	(	Index	idx,
		B	b )

inline

Pushes an element into the B stream with the given index.

If the last element in the B queue has the same index, its value is updated in place. Otherwise the element is appended and drain is called to process any new matches. The queue is trimmed if it exceeds half the index range.

Parameters

[in]	idx	The index associated with this element.
[in]	b	The element value to push.

Definition at line 111 of file IndexMatchQueue.h.

References drain(), and HalfRange().

◆ seqLess()

template<class t_a, class t_b, class t_index = uint04>

constexpr bool IndexMatchQueue< t_a, t_b, t_index >::seqLess	(	Index	a,
		Index	b )

inlinestaticconstexprprotectednoexcept

Determines whether index a precedes index b in circular sequence order.

Parameters

[in]	a	The first index.
[in]	b	The second index.

Returns: True if a is strictly before b in the circular index space.

Definition at line 159 of file IndexMatchQueue.h.

References HalfRange().

Referenced by drain().

◆ setOnMatch()

template<class t_a, class t_b, class t_index = uint04>

void IndexMatchQueue< t_a, t_b, t_index >::setOnMatch ( OnMatchFn on_match )

inline

Sets the callback for exact index matches.

Parameters

[in] on_match Callback invoked when an exact index match is found.

Definition at line 57 of file IndexMatchQueue.h.

◆ setOnNearMatch()

template<class t_a, class t_b, class t_index = uint04>

void IndexMatchQueue< t_a, t_b, t_index >::setOnNearMatch ( OnNearMatchFn on_near_match )

inline

Sets the callback for near index matches.

Parameters

[in] on_near_match Callback invoked when a near index match is found within tolerance.

Definition at line 66 of file IndexMatchQueue.h.

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

Base/Headers/IndexMatchQueue.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IndexMatchQueue()

Member Function Documentation

◆ circularDistance()

◆ drain()

◆ HalfRange()

◆ pushA()

◆ pushB()

◆ seqLess()

◆ setOnMatch()

◆ setOnNearMatch()