CVB++ 14.0
MultiStreamHandler Class Reference

Handler object for multiple synchronous streams. More...

#include <cvb/async/multi_stream_handler.hpp>

Inherited by SingleStreamHandler.

Public Member Functions

void Run ()
 Start the handler. More...
 
bool TryFinish () noexcept
 Stop the handler. More...
 
void Finish ()
 Stop the handler. More...
 
bool IsActive () const noexcept
 Check if the acquisition thread is running. More...
 

Static Public Member Functions

static std::unique_ptr< MultiStreamHandlerCreate (const std::vector< Driver::StreamPtr > &streamVector)
 Create a stream handler object. More...
 

Protected Member Functions

virtual void HandleAsyncStream (const std::vector< Driver::StreamPtr > &streamVector)
 Asynchronously called for all registered streams. More...
 
virtual void HandleAsyncWaitResult (const std::vector< Driver::WaitResult< Driver::StreamImage > > &waitResultVector)
 Asynchronously called for all acquired images. More...
 
virtual void Setup (const std::vector< Driver::StreamPtr > streamVector)
 Setup the streams for acquisition. More...
 
virtual void TearDown (const std::vector< Driver::StreamPtr > streamVector) noexcept
 Tear down the streams after acquisition. More...
 
virtual void HandleError (const std::exception &error) noexcept
 Handles standard exceptions in the acquisition thread. More...
 
virtual void Begin () noexcept
 Performs custom operations at the beginning of the acquisition thread. More...
 
virtual void End () noexcept
 Performs custom operations just before the end of the acquisition thread. More...
 
 MultiStreamHandler (const std::vector< Driver::StreamPtr > &streamVector)
 Creates a stream handler object. More...
 
std::vector< StreamPtr > StreamVector () const noexcept
 Get the streams associated with this handler. More...
 

Detailed Description

Handler object for multiple synchronous streams.

This handler provides a convenient way to acquire images from multiple synchronous streams within a dedicated thread. All streams for this handler must be synchronously (exactly the same frame rate). If this is not the case you will loose images. Please be aware, that there is no way for the application to verify, that the streams are synchronized. For multiple devices usually an external electrical synchronizations mechanism is provided.

For a single stream see SingleStreamHandler.

Example:
class MyMultiStreamHandler
{
public:
MyMultiStreamHandler(const std::vector<Cvb::StreamPtr> & streamVector)
:MultiStreamHandler(streamVector)
{
}
private:
void HandleAsyncStream(const std::vector<Cvb::StreamPtr> &streamVector) override
{
auto readData = 0;
for (auto & stream : streamVector)
{
auto result = stream->WaitFor<Cvb::RingBufferImage>(std::chrono::milliseconds(500));
// Do something.
}
}
};
Handler object for multiple synchronous streams.
Definition: decl_multi_stream_handler.hpp:64
virtual void HandleAsyncStream(const std::vector< Driver::StreamPtr > &streamVector)
Asynchronously called for all registered streams.
Definition: detail_multi_stream_handler.hpp:93
Stream image that is returned, when the ring buffer interface is available on a device.
Definition: decl_ring_buffer_image.hpp:29

Constructor & Destructor Documentation

◆ MultiStreamHandler()

MultiStreamHandler ( const std::vector< Driver::StreamPtr > &  streamVector)
inlineprotected

Creates a stream handler object.

Parameters
[in]streamVectorList with synchronous streams.
Exceptions
Anyexception derived from std::exception including CvbException.

Call this in a customized subclass to setup the handler.

Member Function Documentation

◆ Begin()

virtual void Begin ( )
inlineprotectedvirtualnoexcept

Performs custom operations at the beginning of the acquisition thread.

Exceptions
Doesnot throw any exception.

The default implementation does nothing. Be aware, that this method is called from the acquisition thread. Reimplemented it to setup resources that require the acquisition thread up and running. This is useful for interaction with Qt. E.g. you may create QObject derived classes here to archive correct thread affinity.

◆ Create()

static std::unique_ptr< MultiStreamHandler > Create ( const std::vector< Driver::StreamPtr > &  streamVector)
inlinestatic

Create a stream handler object.

Parameters
[in]streamVectorList with synchronous streams.
Returns
A stream handler object.
Exceptions
Anyexception derived from std::exception including CvbException.
Note
You must not destroy a stream handler that is currently running. In order to prevent that you may use a StreamHandlerGuard.

◆ End()

virtual void End ( )
inlineprotectedvirtualnoexcept

Performs custom operations just before the end of the acquisition thread.

Exceptions
Doesnot throw any exception.

The default implementation does nothing. Be aware, that this method is called from the acquisition thread. Reimplemented it to free resources that have been allocated in Begin().

◆ Finish()

void Finish ( )
inline

Stop the handler.

Exceptions
Anyexception derived from std::exception including CvbException this also includes the last error on the acquisition thread.

This will stop the acquisition thread and call TearDown() on the calling thread. This blocks until the acquisition thread has finished, so blocking in a customized HandleAsyncStream() method can lead to deadlocks.

Note
If the acquisition handler is destroyed it automatically finishes.

◆ HandleAsyncStream()

void HandleAsyncStream ( const std::vector< Driver::StreamPtr > &  streamVector)
inlineprotectedvirtual

Asynchronously called for all registered streams.

Parameters
[in]streamVectorList with synchronous streams (provided at creation).
Exceptions
Anyexception derived from std::exception including CvbException.

The default implementation just waits for the next image on each stream.

Attention
This method is called on a dedicated thread!

◆ HandleAsyncWaitResult()

void HandleAsyncWaitResult ( const std::vector< Driver::WaitResult< Driver::StreamImage > > &  waitResultVector)
inlineprotectedvirtual

Asynchronously called for all acquired images.

Parameters
[in]waitResultVectorList with synchronous acquired WaitResults.
Exceptions
Anyexception derived from std::exception including CvbException.

The default implementation does nothing.

Attention
This method is called on a dedicated thread!

◆ HandleError()

void HandleError ( const std::exception error)
inlineprotectedvirtualnoexcept

Handles standard exceptions in the acquisition thread.

Parameters
[in]&errorThe exception thrown.
Exceptions
Doesnot throw any exception.

This handler is called for all not explicitly handled standard exception in the acquisition thread. After the handler returned the acquisition thread may finish, but remain in the active state. Be aware that this handler is by default called from the acquisition thread.

Note
After this handler there will be no automatic call to TearDown(). So you have to call Finish() explicitly. If you reimplemented this handler you should call the default implementation so Finish() will deliver the error into the controlling thread, otherwise the error will be swallowed within the acquisition thread.

◆ IsActive()

bool IsActive ( ) const
inlinenoexcept

Check if the acquisition thread is running.

Returns
True if running otherwise false.
Exceptions
Doesnot throw any exception.

◆ Run()

void Run ( )
inline

Start the handler.

Exceptions
Anyexception derived from std::exception including CvbException.

This will call Setup() on the calling thread, before createing a dedicated acquisition thread. The acquisition thread will repeatedly call HandleAsyncStream().

◆ Setup()

void Setup ( const std::vector< Driver::StreamPtr streamVector)
inlineprotectedvirtual

Setup the streams for acquisition.

Parameters
[in]streamVectorList with synchronous streams (provided at creation).
Exceptions
Anyexception derived from std::exception including CvbException.

The default implementation just calls Stream::Start() for each stream.

◆ StreamVector()

std::vector< StreamPtr > StreamVector ( ) const
inlineprotectednoexcept

Get the streams associated with this handler.

Returns
Stream vector.
Exceptions
Doesnot throw any exception.

◆ TearDown()

void TearDown ( const std::vector< Driver::StreamPtr streamVector)
inlineprotectedvirtualnoexcept

Tear down the streams after acquisition.

Parameters
[in]streamVectorList with synchronous streams (provided at creation).
Exceptions
Doesnot throw any exception.

The default implemntation just calls Stream::TryAbort() for each stream.

◆ TryFinish()

bool TryFinish ( )
inlinenoexcept

Stop the handler.

Returns
True if no error occurred in the acquisition thread, otherwise.
Exceptions
Doesnot throw any exception.

This will stop the acquisition thread and call TearDown() on the calling thread. This blocks until the acquisition thread has finished, so blocking in a customized HandleAsyncStream() method can lead to deadlocks.

Note
If the acquisition handler is destroyed it automatically finishes.