Thread safe queue. More...

#include <Utils.h>

Inheritance diagram for esi::utils::TSQueue< T >:

Collaboration diagram for esi::utils::TSQueue< T >:

[legend]

Public Member Functions
	TSQueue ()=default
	Default constructor: no external notifier.

	TSQueue (std::function< void()> notifier)
	Construct a queue that calls `notifier` after every successful `push`, once the queue mutex has been released.

template<typename... E>
void	push (E... t)
	Push onto the queue.

std::optional< T >	pop ()
	Pop something off the queue but return nullopt if the queue is empty.

std::optional< T >	waitPop ()
	Block until an item is available or `requestShutdown()` is called.

void	pop (std::function< bool(const T &)> callback)
	Call the callback for the front of the queue (if anything is there).

bool	empty () const
	Is the queue empty?

void	requestShutdown ()
	Permanently retire the queue: wake every current and future `waitPop()` with `nullopt` so consumer threads can exit cleanly.

bool	isShutdown () const
	True once `requestShutdown()` has been called.

Private Types
using	Lock = std::lock_guard< std::mutex >

Private Attributes
std::mutex	qM
	The queue and its mutex.

std::queue< T >	q

std::condition_variable	cv
	CV signalled by `push` and `requestShutdown`.

bool	shutdown = false

const std::function< void()>	notifier
	Optional external notifier invoked after `push` releases the queue lock.

std::mutex	popM
	A mutex to ensure that only one 'pop' operation is happening at a time.

Detailed Description

template<typename T>
class esi::utils::TSQueue< T >

Thread safe queue.

Just wraps std::queue protected with a lock. Long term, we need to avoid copying data. It has a lot of data copies currently.

Push operations notify a built-in condition variable so consumers can block on waitPop() rather than poll. requestShutdown() permanently wakes any waiters with nullopt, which is how owners cleanly retire a drainer thread.

Definition at line 48 of file Utils.h.

Member Typedef Documentation

◆ Lock

template<typename T >

using esi::utils::TSQueue< T >::Lock = std::lock_guard<std::mutex>

private

Definition at line 49 of file Utils.h.

Constructor & Destructor Documentation

◆ TSQueue() [1/2]

template<typename T >

esi::utils::TSQueue< T >::TSQueue ( )

default

Default constructor: no external notifier.

◆ TSQueue() [2/2]

template<typename T >

esi::utils::TSQueue< T >::TSQueue ( std::function< void()> notifier )

inlineexplicit

Construct a queue that calls notifier after every successful push, once the queue mutex has been released.

Use this to ring an external doorbell (e.g. a server-wide "ports with pending data" set) without making every push site know about it. The notifier is fixed for the lifetime of the queue — there is no setter, because changing it while other threads are pushing would be a data race.

Definition at line 80 of file Utils.h.

Member Function Documentation

◆ empty()

template<typename T >

bool esi::utils::TSQueue< T >::empty ( ) const

inline

Is the queue empty?

Definition at line 143 of file Utils.h.

References esi::utils::TSQueue< T >::q, and esi::utils::TSQueue< T >::qM.

◆ isShutdown()

template<typename T >

bool esi::utils::TSQueue< T >::isShutdown ( ) const

inline

True once requestShutdown() has been called.

Definition at line 160 of file Utils.h.

References esi::utils::TSQueue< T >::qM, and esi::utils::TSQueue< T >::shutdown.

◆ pop() [1/2]

template<typename T >

std::optional< T > esi::utils::TSQueue< T >::pop ( )

inline

Pop something off the queue but return nullopt if the queue is empty.

Why doesn't std::queue have anything like this?

Definition at line 98 of file Utils.h.

References esi::utils::TSQueue< T >::popM, esi::utils::TSQueue< T >::q, and esi::utils::TSQueue< T >::qM.

◆ pop() [2/2]

template<typename T >

void esi::utils::TSQueue< T >::pop ( std::function< bool(const T &)> callback )

inline

Call the callback for the front of the queue (if anything is there).

Only pop it off the queue if the callback returns true.

Definition at line 123 of file Utils.h.

References esi::utils::TSQueue< T >::popM, esi::utils::TSQueue< T >::q, and esi::utils::TSQueue< T >::qM.

◆ push()

template<typename T >

template<typename... E>

void esi::utils::TSQueue< T >::push ( E... t )

inline

Push onto the queue.

Wakes one waitPop() waiter (if any) and rings the external notifier, if one was supplied to the constructor.

Definition at line 86 of file Utils.h.

References esi::utils::TSQueue< T >::cv, esi::utils::TSQueue< T >::notifier, esi::utils::TSQueue< T >::q, and esi::utils::TSQueue< T >::qM.

◆ requestShutdown()

template<typename T >

void esi::utils::TSQueue< T >::requestShutdown ( )

inline

Permanently retire the queue: wake every current and future waitPop() with nullopt so consumer threads can exit cleanly.

Pushes after this still enqueue, but no one is expected to be waiting.

Definition at line 151 of file Utils.h.

References esi::utils::TSQueue< T >::cv, esi::utils::TSQueue< T >::qM, and esi::utils::TSQueue< T >::shutdown.

◆ waitPop()

template<typename T >

std::optional< T > esi::utils::TSQueue< T >::waitPop ( )

inline

Block until an item is available or requestShutdown() is called.

Returns nullopt only in the shutdown case. Intended for single-consumer drainer threads; do not interleave with pop() on the same queue.

Definition at line 111 of file Utils.h.

References esi::utils::TSQueue< T >::cv, esi::utils::TSQueue< T >::q, esi::utils::TSQueue< T >::qM, and esi::utils::TSQueue< T >::shutdown.

Member Data Documentation

◆ cv

template<typename T >

std::condition_variable esi::utils::TSQueue< T >::cv

private

CV signalled by push and requestShutdown.

Waiters re-check the predicate under qM so missed notifications are recovered.

Definition at line 57 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::push(), esi::utils::TSQueue< T >::requestShutdown(), and esi::utils::TSQueue< T >::waitPop().

◆ notifier

template<typename T >

const std::function<void()> esi::utils::TSQueue< T >::notifier

private

Optional external notifier invoked after push releases the queue lock.

Set once at construction; never mutated afterwards.

Definition at line 62 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::push().

◆ popM

template<typename T >

std::mutex esi::utils::TSQueue< T >::popM

private

A mutex to ensure that only one 'pop' operation is happening at a time.

It is critical that locks be obtained on this and qM same order in both pop methods. This lock should be obtained first since one of the pop methods must unlock qM then relock it.

Definition at line 68 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::pop(), and esi::utils::TSQueue< T >::pop().

◆ q

template<typename T >

std::queue<T> esi::utils::TSQueue< T >::q

private

Definition at line 53 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::empty(), esi::utils::TSQueue< T >::pop(), esi::utils::TSQueue< T >::pop(), esi::utils::TSQueue< T >::push(), and esi::utils::TSQueue< T >::waitPop().

◆ qM

template<typename T >

std::mutex esi::utils::TSQueue< T >::qM

mutableprivate

The queue and its mutex.

Definition at line 52 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::empty(), esi::utils::TSQueue< T >::isShutdown(), esi::utils::TSQueue< T >::pop(), esi::utils::TSQueue< T >::pop(), esi::utils::TSQueue< T >::push(), esi::utils::TSQueue< T >::requestShutdown(), and esi::utils::TSQueue< T >::waitPop().

◆ shutdown

template<typename T >

bool esi::utils::TSQueue< T >::shutdown = false

private

Definition at line 58 of file Utils.h.

Referenced by esi::utils::TSQueue< T >::isShutdown(), esi::utils::TSQueue< T >::requestShutdown(), and esi::utils::TSQueue< T >::waitPop().

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

/home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/include/esi/Utils.h

Public Member Functions

Private Types

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Lock

Constructor & Destructor Documentation

◆ TSQueue() [1/2]

◆ TSQueue() [2/2]

Member Function Documentation

◆ empty()

◆ isShutdown()

◆ pop() [1/2]

◆ pop() [2/2]

◆ push()

◆ requestShutdown()

◆ waitPop()

Member Data Documentation

◆ cv

◆ notifier

◆ popM

◆ q

◆ qM

◆ shutdown