CVB++ 14.1
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
StreamHandlerBase< STREAMTYPE > Class Template Reference

Stream handler for synchronous streams. More...

#include <cvb/async/stream_handler_base.hpp>

Public Types

using StreamType = STREAMTYPE
 Shorthand notation of the stream type.
 
using StreamPtrType = std::shared_ptr< StreamType >
 Shorthand notation of the shared pointer of the specified stream.
 
using StreamVectorType = std::vector< StreamPtrType >
 Shorthand notation of the container of the stream shared pointer.
 
using DeliverableType = typename Internal::DeliverableTraits< STREAMTYPE >::type
 Shorthand notation of the stream deliverable type of the specified stream.
 
using DeliverablePtrType = std::shared_ptr< typename Internal::DeliverableTraits< STREAMTYPE >::type >
 Shorthand notation of the shared pointer of the stream deliverable.
 
using DeliverablePtrVectorType = std::vector< DeliverablePtrType >
 Shorthand notation of the container of the stream deliverable shared pointers.
 
using EventHandlerType = std::function< void(DeliverablePtrType, Cvb::WaitStatus)>
 Shorthand notation of the event handler, a callable, type.
 
using EventHandlerVectorType = std::vector< EventHandlerType >
 Shorthand notation of the container of the event handler.
 

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< StreamHandlerBase > Create (const StreamVectorType &streamVector)
 Create a stream handler object. More...
 
static std::unique_ptr< StreamHandlerBase > Create (const StreamPtrType &stream)
 Create a stream handler object. More...
 

Protected Member Functions

virtual void HandleAsyncStream (const StreamVectorType &streamVector)
 Asynchronously called for all registered streams. More...
 
virtual void HandleAsyncWaitResult (const std::vector< WaitResult< typename Internal::DeliverableTraits< STREAMTYPE >::type > > &waitResultVector)
 Asynchronously called for all acquired images. More...
 
virtual void HandleAsyncWaitResult (const std::vector< WaitResultTuple< typename Internal::DeliverableTraits< STREAMTYPE >::type > > &waitResultVector)
 Asynchronously called for all acquired images. More...
 
virtual void Setup (const StreamVectorType streamVector)
 Setup the streams for acquisition. More...
 
virtual void TearDown (const StreamVectorType 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...
 
 StreamHandlerBase (const StreamVectorType &streamVector)
 Creates a stream handler object. More...
 
 StreamHandlerBase (const StreamPtrType &stream)
 Creates a stream handler object. More...
 
std::vector< StreamPtrType > StreamVector () const noexcept
 Get the streams associated with this handler. More...
 

Detailed Description

template<class STREAMTYPE>
class Cvb::Async::StreamHandlerBase< STREAMTYPE >

Stream handler for synchronous streams.

Template Parameters
STREAMTYPEType of stream to be taken care of.
Examples
Cvb/CppCompositeStreamHandler.

Constructor & Destructor Documentation

◆ StreamHandlerBase() [1/2]

StreamHandlerBase ( const StreamVectorType &  streamVector)
inlineexplicitprotected

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.

◆ StreamHandlerBase() [2/2]

StreamHandlerBase ( const StreamPtrType &  stream)
inlineexplicitprotected

Creates a stream handler object.

Parameters
[in]streamSynchronous stream.
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() [1/2]

static std::unique_ptr< StreamHandlerBase > Create ( const StreamPtrType &  stream)
inlinestatic

Create a stream handler object.

Parameters
[in]streamSynchronous stream.
Returns
A stream handler object.
Exceptions
Anyexception derived from std::exception including CvbException.

This overload can be helpful if it is obvious that the number of streams is limited to one.

Note
You must not destroy a stream handler that is currently running. In order to prevent that you may use a StreamHandlerGuard.

◆ Create() [2/2]

static std::unique_ptr< StreamHandlerBase > Create ( const StreamVectorType &  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.
Examples
Cvb/CppCompositeStreamHandler.

◆ 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 StreamVectorType &  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!
Examples
Cvb/CppCompositeStreamHandler.

◆ HandleAsyncWaitResult() [1/2]

void HandleAsyncWaitResult ( const std::vector< WaitResult< typename Internal::DeliverableTraits< STREAMTYPE >::type > > &  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!
Examples
Cvb/CppCompositeStreamHandler.

◆ HandleAsyncWaitResult() [2/2]

void HandleAsyncWaitResult ( const std::vector< WaitResultTuple< typename Internal::DeliverableTraits< STREAMTYPE >::type > > &  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 creating a dedicated acquisition thread. The acquisition thread will repeatedly call HandleAsyncStream().

◆ Setup()

void Setup ( const StreamVectorType  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< StreamPtrType > StreamVector ( ) const
inlineprotectednoexcept

Get the streams associated with this handler.

Returns
Stream vector.
Exceptions
Doesnot throw any exception.

◆ TearDown()

void TearDown ( const StreamVectorType  streamVector)
inlineprotectedvirtualnoexcept

Tear down the streams after acquisition.

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

The default implementation 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.