BackgroundThreadQueue< T > Class Template Reference

#include <ImFusion/Stream/BackgroundThreadQueue.h>

Queue for thread-safe asynchronous management of some payload data as needed in most streaming classes. More...

Detailed Description

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

Queue for thread-safe asynchronous management of some payload data as needed in most streaming classes.

Holders for this queue may be an stream processing algorithm, especially when the processing rate may exceed the stream frame rate, or if the processing needs an OpenGL context (there is no guarantee the streaming thread has one).

This class is intended to be used together with the BackgroundThreadConsumer interface, for instance by a StreamListener where expensive per-frame computations shall be performed in a dedicated background thread. Let your StreamListener class inherit from BackgroundThreadConsumer and have a BackgroundThreadQueue as member. In the constructor you connect the two and start the BackgroundThreadQueue. In the StreamListener::onStreamData() callback you then enqueue the StreamData so that it will be processed in the background thread.

You can define a maximum queue size that controls the maximum number of elements that can be waiting in the queue to be processed while the consumer is busy.

Public Member Functions
	BackgroundThreadQueue (BackgroundThreadConsumer< T > &consumer, int maxSize=1)
bool	start (bool createOpenGLcontext=false)
	Launch the background thread and returns true if successful.
void	stop ()
	Stops the background thread by signalling it to stop and waiting until it has.
int	currentSize ()
	Returns the current size of the queue.
std::future< void >	enqueueFuture (TimestampedPayload< T > data)
	Adds new payload data to the queue if it's not nullptr.
int	enqueue (TimestampedPayload< T > data)
	Adds new payload data to the queue if it's not nullptr.
void	waitUntilCompleted ()
	Waits until the background thread has processed all queue items, but does not stop it.
void	clearQueueAndWaitUntilCompleted ()
	Clears the queue and waits until any queue item currently being processed is finished.
void	clearQueue ()
	Removes all data from the queue.
int	maxSize () const
	Returns the maximum size.
void	setMaxSize (int s)
	Sets the maximum size.
std::thread::id	backgroundThreadId () const
bool	contains (const std::function< bool(const TimestampedPayload< T > &)> &condition)
	Check if there is an element that satisfies condition

Member Function Documentation

start()

template<typename T>

bool start ( bool createOpenGLcontext = false )

inline

Launch the background thread and returns true if successful.

If createOpenGLcontext is set to true, make sure to call this method from the main thread. If there are remaining elements in the queue from a previous thread, they will be processed first.

stop()

template<typename T>

void stop ( )

inline

Stops the background thread by signalling it to stop and waiting until it has.

If data is currently being processed, this method will block until this terminated. Does not clear the queue.

enqueueFuture()

template<typename T>

std::future< void > enqueueFuture ( TimestampedPayload< T > data )

inlinenodiscard

Adds new payload data to the queue if it's not nullptr.

Will remove the oldest element from the queue if the operation would exceed its maximum size. Returns a future that will be completed when the payload is processed. The future is invalid if the enqueue operation failed.

enqueue()

template<typename T>

int enqueue ( TimestampedPayload< T > data )

inline

Adds new payload data to the queue if it's not nullptr.

Will remove the oldest element from the queue if the operation would exceed its maximum size. Returns -1 if enqueue operation failed, otherwise the current queue size.

waitUntilCompleted()

template<typename T>

void waitUntilCompleted ( )

inline

Waits until the background thread has processed all queue items, but does not stop it.

This call will block until the queue is empty. Do NOT call while there are still new payload items being added to the queue. Useful for automated test cases.

clearQueueAndWaitUntilCompleted()

template<typename T>

void clearQueueAndWaitUntilCompleted ( )

inline

Clears the queue and waits until any queue item currently being processed is finished.

This call will block until the queue is empty. Do NOT call while there are still new payload items being added to the queue. Useful for automated test cases.

setMaxSize()

template<typename T>

void setMaxSize ( int s )

inline

Sets the maximum size.

Removes excess elements from the queue, if necessary.

---

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

• ImFusion/Stream/BackgroundThreadConsumer.h
• ImFusion/Stream/BackgroundThreadQueue.h