ImFusion::ThreadSafeQueue< T > Class Template Reference

#include <ImFusion/Stream/ThreadSafeQueue.h>

Thread-safe queue wrapper around std::queue with blocking wait support. More...

Inheritance diagram for ImFusion::ThreadSafeQueue< T >:

Detailed Description

template<typename T>
class ImFusion::ThreadSafeQueue< T >

Thread-safe queue wrapper around std::queue with blocking wait support.

Provides basic queue operations with thread-safety guarantees using a mutex and condition variable. Supports both non-blocking (tryPop) and blocking (waitAndPop) pop operations.

The queue can be shut down via shutdown(), which will decline future push operations and wake all waiting threads to cause waitAndPop() to return std::nullopt once the queue is empty.

Note

This queue is suitable for unbounded (infinite size) queues with non-trivially destructible types. For alternative implementations consider:

• boost::lockfree::queue<T> for trivially destructible types (lock-free)
• boost::lockfree::spsc_queue<T> for bounded queues with a single producer and single consumer (lock-free, fixed capacity)

Lifetime issue: shutdown() is called and all threads must have exited waitAndPop() when the queue is destroyed. This allows to continuously call waitAndPop() in a while loop without running into lifetime issues (see example).

Example usage with producer and consumer on different threads:

ThreadSafeQueue<int> queue;
 
// Consumer: runs until shutdown
auto consumer = std::async(std::launch::async, [&queue]() {
    // this is safe even when the queue is deleted on another thread
    while (auto val = queue.waitAndPop())
    {
        processItem(*val);
    }
});
 
// Producer: add items
for (int i = 0; i < 100; ++i)
    queue.push(i);
 
// Cleanup: shutdown and wait for consumer
queue.shutdown();
consumer.get();

Note

Threadsafe class: Member functions can be called concurrently from any thread.

Public Member Functions
	~ThreadSafeQueue ()
	Destructor ensures that stalling waitAndPop() calls terminate.
bool	push (T value)
	Pushes an element to the back of the queue if the queue wasn't shut down yet.
std::optional< T >	tryPop ()
	Attempts to pop an element from the front of the queue without blocking.
std::optional< T >	waitAndPop ()
	Blocks until an element becomes available or shutdown() is called.
void	shutdown ()
	Signals shutdown and wakes all threads waiting in waitAndPop().
bool	empty () const
	Checks if the queue is empty.
int	size () const
	Returns the number of elements in the queue.

Protected Member Functions
int	waitingConsumers () const
Protected Member Functions inherited from ImFusion::Utils::NotCopyable
	NotCopyable (NotCopyable &&) noexcept=default
NotCopyable &	operator= (NotCopyable &&) noexcept=default
	NotCopyable (const NotCopyable &)=delete
NotCopyable &	operator= (const NotCopyable &)=delete

Member Function Documentation

push()

template<typename T>

bool ImFusion::ThreadSafeQueue< T >::push ( T value )

inline

Pushes an element to the back of the queue if the queue wasn't shut down yet.

Returns if push operation was successful. Notifies one waiting thread that an element is available.

tryPop()

template<typename T>

std::optional< T > ImFusion::ThreadSafeQueue< T >::tryPop ( )

inline

Attempts to pop an element from the front of the queue without blocking.

Returns

The front element if the queue is not empty, std::nullopt otherwise.

waitAndPop()

template<typename T>

std::optional< T > ImFusion::ThreadSafeQueue< T >::waitAndPop ( )

inline

Blocks until an element becomes available or shutdown() is called.

Returns

The front element if available, std::nullopt if the queue was shut down.

shutdown()

template<typename T>

void ImFusion::ThreadSafeQueue< T >::shutdown ( )

inline

Signals shutdown and wakes all threads waiting in waitAndPop().

After calling this, no further elements can be added to the queue and waitAndPop() will return std::nullopt for waiting threads if the queue is empty.

empty()

template<typename T>

bool ImFusion::ThreadSafeQueue< T >::empty ( ) const

inline

Checks if the queue is empty.

Note

The result may be outdated immediately after the call in multi-threaded contexts.

size()

template<typename T>

int ImFusion::ThreadSafeQueue< T >::size ( ) const

inline

Returns the number of elements in the queue.

Note

The result may be outdated immediately after the call in multi-threaded contexts.

---

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

• ImFusion/Stream/ThreadSafeQueue.h