reference

This documentation is automatically generated from the openFrameworks source code using doxygen and refers to the most recent release, version 0.12.0.

ofThreadChannel< T > Class Template Reference

Safely send data between threads without additional synchronization. More...

#include <ofThreadChannel.h>

Public Member Functions

 ofThreadChannel ()
 Create a default ofThreadChannel.
 
bool receive (T &sentValue)
 Block the receiving thread until a new sent value is available.
 
bool tryReceive (T &sentValue)
 If available, receive a new sent value without blocking.
 
bool tryReceive (T &sentValue, int64_t timeoutMs)
 If available, receive a new sent value or wait for a user-specified duration.
 
bool send (const T &value)
 Send a value to the receiver by making a copy.
 
bool send (T &&value)
 Send a value to the receiver without making a copy.
 
void close ()
 Close the ofThreadChannel.
 
bool empty () const
 Queries empty channel.
 
size_t size () const
 Queries size of queue.
 

Detailed Description

template<typename T>
class ofThreadChannel< T >

Safely send data between threads without additional synchronization.

ofThreadChannel makes it easy to safely and efficiently share data between threads without the need for shared memory, mutexes, or other synchronization techniques. Additionally, ofThreadChannel employs a signalling system that allows receiving threads to sleep until new data arrives or the ofThreadChannel is closed.

A single ofThreadChannel class is designed for one-way communication. In most cases an additional ofThreadChannel can be used for two-way communication.

Data is sent through the ofThreadChannel in a FIFO (first in, first out) order, guaranteeing that that data will be received in the same order that it was sent.

If multiple threads attempt to send data using the same ofThreadChannel, the send method will block the calling thread until it is free.

See also
https://github.com/openframeworks/ofBook/blob/master/chapters/threads/chapter.md
Template Parameters
TThe data type sent by the ofThreadChannel.

Constructor & Destructor Documentation

◆ ofThreadChannel()

template<typename T >
ofThreadChannel< T >::ofThreadChannel ( )
inline

Create a default ofThreadChannel.

ofThreadChannel must be instantiated with a template parameter such as:

ofThreadChannel<ofPixels> myThreadChannel;
Safely send data between threads without additional synchronization.
Definition ofThreadChannel.h:29

Member Function Documentation

◆ close()

template<typename T >
void ofThreadChannel< T >::close ( )
inline

Close the ofThreadChannel.

Closing the ofThreadChannel means that no new messages can be sent or received. All threads waiting to receive new values will be notified and all ofThreadChannel::receive and ofThreadChannel::tryReceive methods will return false.

◆ empty()

template<typename T >
bool ofThreadChannel< T >::empty ( ) const
inline

Queries empty channel.

This call is only an approximation, since messages come from a different thread the channel can return true when calling empty() and then receive a message right afterwards

◆ receive()

template<typename T >
bool ofThreadChannel< T >::receive ( T &  sentValue)
inline

Block the receiving thread until a new sent value is available.

The receiving thread will block until a new sent value is available. In order to receive data, the user must create an instance of the data type, and pass it to the receive method to be set.

ofThreadChannel::receive will not make a copy or reallocate data.

ofThreadChannel<ofPixels> myThreadChannel;
// ofThreadChannel<ofPixels> declared elsewhere.
ofPixels myPixelsToSet;
if (myThreadChannel.receive(myPixelsToSet)) {
// If true, `myPixelsToSet` can be used.
} else {
// If false, thread channel was closed and the value of
// `myPixelsToSet` may be invalid depending on the scope of
// `myPixelsToSet`.
}
bool receive(T &sentValue)
Block the receiving thread until a new sent value is available.
Definition ofThreadChannel.h:66
Parameters
sentValueA reference to a sent value.
Returns
True if a new value was received or false if the ofThreadChannel was closed.

◆ send() [1/2]

template<typename T >
bool ofThreadChannel< T >::send ( const T &  value)
inline

Send a value to the receiver by making a copy.

This method copies the contents of the sent value, leaving the original data unchanged.

ofThreadChannel<ofPixels> myThreadChannel;
// ofThreadChannel<ofPixels> initialized elsewhere.
ofPixels myPixelsToSend;
// Fill the pixels with valid data, an image for example.
ofLoadImage(myPixelsToSend, "myImage.jpg");
// Send `myPixelsToSend` by copying it. `myPixelsToSend` is still valid
// after sending.
if (myThreadChannel.send(myPixelsToSend)) {
// If true, `myPixelsToSend` was sent successfully.
} else {
// If false, the thread channel was closed.
}
bool send(const T &value)
Send a value to the receiver by making a copy.
Definition ofThreadChannel.h:206
bool ofLoadImage(ofPixels &pix, const of::filesystem::path &path, const ofImageLoadSettings &settings)
Definition ofImage.cpp:302
Returns
true if the value was sent successfully or false if the channel was closed.

◆ send() [2/2]

template<typename T >
bool ofThreadChannel< T >::send ( T &&  value)
inline

Send a value to the receiver without making a copy.

This method moves the contents of the sent value using std::move semantics. This avoids copying the data, but the original data data will be invalidated. Note that the original data will be invalideated even if the send fails because the channel is already closed.

ofThreadChannel<ofPixels> myThreadChannel;
// ofThreadChannel<ofPixels> initialized elsewhere.
ofPixels myPixelsToSend;
// Fill the pixels with valid data, an image for example.
ofLoadImage(myPixelsToSend, "myImage.jpg");
// Send `myPixelsToSend` by moving it. `myPixelsToSend` will no longer
// be valid, even if the send fails because the channel is closed.
if (myThreadChannel.send(std::move(myPixelsToSend))) {
// If true, `myPixelsToSend` was sent successfully.
// `myPixelsToSend` is no longer valid because it was moved.
} else {
// If false, the thread channel was closed.
// `myPixelsToSend` is no longer valid because it was moved.
}
Returns
true if the value was sent successfully or false if the channel was closed.

◆ size()

template<typename T >
size_t ofThreadChannel< T >::size ( ) const
inline

Queries size of queue.

This call is only an approximation, since messages come from a different thread.

◆ tryReceive() [1/2]

template<typename T >
bool ofThreadChannel< T >::tryReceive ( T &  sentValue)
inline

If available, receive a new sent value without blocking.

ofThreadChannel::tryReceive is similar to ofThreadChannel::receive, except that it will not block the receiving thread. If no data is available, it will return false and continue immediately.

ofThreadChannel::tryReceive will not make a copy or reallocate data.

Like ofThreadChannel::receive, in order to receive data, the user must create an instance of the data type, and pass it to the receive method to be set.

ofThreadChannel<ofPixels> myThreadChannel;
// ofThreadChannel<ofPixels> initialized elsewhere.
ofPixels myPixelsToSet;
if (myThreadChannel.tryReceive(myPixelsToSet)) {
// If true, `myPixelsToSet` can be used.
} else {
// If false, there was no new data OR the thread channel was closed.
// Either way, the value of `myPixelsToSet` may be invalid depending
// on the scope of `myPixelsToSet`.
}
bool tryReceive(T &sentValue)
If available, receive a new sent value without blocking.
Definition ofThreadChannel.h:113
Parameters
sentValueA reference to a sent value.
Returns
True if a new value was received or false if the ofThreadChannel was closed.

◆ tryReceive() [2/2]

template<typename T >
bool ofThreadChannel< T >::tryReceive ( T &  sentValue,
int64_t  timeoutMs 
)
inline

If available, receive a new sent value or wait for a user-specified duration.

ofThreadChannel::tryReceive is similar to ofThreadChannel::receive, except that it will block the receiving thread for a maximum of timeoutMs while it waits for sent data. If no data is available during that time, it will return false and continue.

ofThreadChannel::tryReceive will not make a copy or reallocate data.

Like ofThreadChannel::receive, in order to receive data, the user must create an instance of the data type, and pass it to the receive method to be set.

ofThreadChannel<ofPixels> myThreadChannel;
// ofThreadChannel<ofPixels> initialized elsewhere.
ofPixels myPixelsToSet;
if (myThreadChannel.tryReceive(myPixelsToSet)) {
// If true, `myPixelsToSet` can be used.
} else {
// If false, there was no new data OR the thread channel was closed.
// Either way, the value of `myPixelsToSet` may be invalid depending
// on the scope of `myPixelsToSet`.
}
Parameters
sentValueA reference to a sent value.
timeoutMsThe number of milliseconds to wait for new data before continuing.
Returns
True if a new value was received or false if the ofThreadChannel was closed.

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