cSubstreamHandling

Utility class to handle substream routing within a filter. More...

Inheritance diagram for cSubstreamHandling:

Public Types
using	tSampleCallback = std::function< void(const adtf::ucom::iobject_ptr< const adtf::streaming::ISample > &)>
	a function that processes samples
using	tGeneratorCallback = std::function< tSampleCallback(const adtf::ucom::iobject_ptr< const adtf::streaming::IStreamType > &)>
	a function that generates a function that processes samples for a given stream type.
using	tNamedGeneratorCallback = std::function< tSampleCallback(const std::string &, const adtf::ucom::iobject_ptr< const adtf::streaming::IStreamType > &)>
	a function that generates a function that processes samples for a given substream name and stream type.
using	tElementValue = std::variant< bool, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float, double >

Public Member Functions
	cSubstreamHandling ()
	Constructs an empty object that cannot perform any operations other than being assigned another value.
	cSubstreamHandling (adtf::filter::hollow::cGraphObject *pFilter, const std::string &strInputPinName, bool bForwardTriggerViaOutputPins=true)
	Constructs a new object that will create an input pin at the given graph object (i.e. More...
	cSubstreamHandling (cSubstreamHandling &&oOther)
cSubstreamHandling &	operator= (cSubstreamHandling &&oOther)
	cSubstreamHandling (const cSubstreamHandling &)=delete
cSubstreamHandling &	operator= (const cSubstreamHandling &)=delete
void	AddSubstreamHandler (const std::string &strName, tGeneratorCallback fnGeneratorCallback)
	Installs a handler generator for the given substream. More...
void	AddSubstreamHandler (const std::regex &strNameExpression, tNamedGeneratorCallback fnGeneratorCallback)
	Installs a handler generator that will be called for each available substream that matches the regular expression This allows you to assign handlers based on name and the stream type. More...
void	AddSubstreamHandler (const std::string &strName, tSampleCallback fnCallback)
	Installs a handler for samples of the given substream. More...
void	AddElementHandler (const std::string &strSubstreamName, const std::string &strElementName, std::function< void(adtf::base::flash::tNanoSeconds, tElementValue)> fnCallback, bool bNameHeuristic=false)
	Installs a handler for the given element of the given substream. More...
template<typename T >
void	AddElementHandler (const std::string &strSubstreamName, const std::string &strElementName, std::function< void(adtf::base::flash::tNanoSeconds, T)> fnCallback, bool bNameHeuristic=false)
	Installs a handler for the given element of the given substream. More...
void	RemoveAllHandlers ()
	Removes all installed handlers. More...

Private Attributes
std::unique_ptr< cImplementation >	m_pImplementation

Detailed Description

Utility class to handle substream routing within a filter.

This class will perform all the substream request handling and routing for you. You can create multiple instances within one filter to seperate multiple inputs. if you only require a single input, you can also use cSubstreamFilter or substream_filter.

An example usage would look like this:

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
        
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
            m_oInput.AddSubstreamHandler("your.substream.name", [](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
            {
                LOG_INFO("received a sample on substream 'your.substream.name'");
            });
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};

Definition at line 35 of file substream_handling.h.

Constructor & Destructor Documentation

cSubstreamHandling()

cSubstreamHandling	(	adtf::filter::hollow::cGraphObject *	pFilter,
		const std::string &	strInputPinName,
		bool	bForwardTriggerViaOutputPins = true
	)

Constructs a new object that will create an input pin at the given graph object (i.e.

filter).

Example Usage

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
        
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
            m_oInput.AddSubstreamHandler("your.substream.name", [](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
            {
                LOG_INFO("received a sample on substream 'your.substream.name'");
            });
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};

Parameters

[in]	pFilter	The filter instance where the input pin should be created at.
[in]	strInputPinName	The name of the input pin.
[in]	bForwardTriggerViaOutputPins	If true, triggers will be forwarded via all output pins after all handlers were called.

Member Function Documentation

AddElementHandler() [1/2]

void AddElementHandler ( const std::string &  strSubstreamName, const std::string &  strElementName, std::function< void(adtf::base::flash::tNanoSeconds, T)>  fnCallback, bool  bNameHeuristic = false  )

inline

Installs a handler for the given element of the given substream.

Use this version when you need the element value in a specific type (i.e. double)

Example Usage

m_oInput.AddElementHandler<uint32_t>("your.substream.name", "the.name.of.the.structure.element", [](adtf::base::tNanoSeconds tmTimeStamp, uint32_t nValue)
{
    LOG_INFO("received an element value of %" PRIu32, nValue);
});

Template Parameters

T	The type that the element value should be converted to.

Parameters

[in]	strSubstreamName	The name of the substream.
[in]	strElementName	The elements name i.e. "first.second.leaf"
[in]	fnCallback	This is called with the timestamp and the value of the element whenever a sample is recieved.
[in]	bNameHeuristic	If true, different variants of the element name will be tried as well (i.e. with ".phy" or ".raw" appended, etc.)

Definition at line 150 of file substream_handling.h.

References cSubstreamHandling::AddElementHandler().

AddElementHandler() [2/2]

void AddElementHandler	(	const std::string &	strSubstreamName,
		const std::string &	strElementName,
		std::function< void(adtf::base::flash::tNanoSeconds, tElementValue)>	fnCallback,
		bool	bNameHeuristic = false
	)

Installs a handler for the given element of the given substream.

The element value is handed over as a variant containing the original element value type. You can use std::visit to access the contained value in a type safe manner.

There is also a convenience template function AddElementHandler<> in case you want the value in a specific type. (i.e. double)

Example Usage

m_oInput.AddElementHandler("your.substream.name", "the.name.of.the.structure.element", [](adtf::base::tNanoSeconds tmTimeStamp, adtf::filter::cSubstreamHandling::tElementValue xValue)
{
    LOG_INFO("received an element value of type: %zu", xValue.index());
 
    // you can use std::visit() to access the value in a type safe manner.                
});

Parameters

[in]	strSubstreamName	The name of the substream.
[in]	strElementName	The elements name i.e. "first.second.leaf"
[in]	fnCallback	This is called with the timestamp and the value of the element whenever a sample is recieved.
[in]	bNameHeuristic	If true, different variants of the element name will be tried as well (i.e. with ".phy" or ".raw" appended, etc., elements representing physical values will be preferred)

Referenced by cSubstreamHandling::AddElementHandler().

AddSubstreamHandler() [1/3]

void AddSubstreamHandler	(	const std::regex &	strNameExpression,
		tNamedGeneratorCallback	fnGeneratorCallback
	)

Installs a handler generator that will be called for each available substream that matches the regular expression This allows you to assign handlers based on name and the stream type.

Example Usage

m_oInput.AddSubstreamHandler(std::regex("my_prefix_.*"), [](const std::string& strSubstreamName, const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>& pType)
{
    return [strSubstreamName](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample) // you can pass along/store required data via the lambda capture clause
    {
        LOG_INFO("received a sample on substream '%s'", strSubstreamName.c_str());    
    };
});

Parameters

[in]

fnGeneratorCallback

This is called for each substream whenever the stream type changes. Return an empty std::function when you want to ignore a certain substream.

AddSubstreamHandler() [2/3]

void AddSubstreamHandler	(	const std::string &	strName,
		tGeneratorCallback	fnGeneratorCallback
	)

Installs a handler generator for the given substream.

This allows you to assign handlers based on the stream type.

Example Usage

m_oInput.AddSubstreamHandler("your.substream.name", [](const adtf::ucom::iobject_ptr<const adtf::streaming::IStreamType>& pType)
{
    std::string strMetaType;
    pType->GetMetaTypeName(adtf_string_intf(strMetaType));
    LOG_INFO("Found substream 'your.substream.name' with type '%s'", strMetaType.c_str());
 
    return [strMetaType](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample) // you can pass along/store required data via the lambda capture clause
    {
        LOG_INFO("received a sample on substream 'your.substream.name' with type '%s'", strMetaType.c_str());    
    };
});

Parameters

[in]	strName	The name of the substream.
[in]	fnGeneratorCallback	This is called whenever a stream becomes available. Return an empty std::function when you want to ignore the substream.

AddSubstreamHandler() [3/3]

void AddSubstreamHandler	(	const std::string &	strName,
		tSampleCallback	fnCallback
	)

Installs a handler for samples of the given substream.

Example Usage

m_oInput.AddSubstreamHandler("your.substream.name", [](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
{
    LOG_INFO("received a sample on substream 'your.substream.name'");
});

Parameters

[in]	strName	The name of the substream.
[in]	tSampleCallback	This is called for each received sample.

RemoveAllHandlers()

void RemoveAllHandlers

(

)

Removes all installed handlers.

Call this in the aquivalent shutdown stage to where you added them.

Example Usage

#include <adtffiltersdk/adtf_filtersdk.h>
 
class cMyFilter: public adtf::filter::cFilter
{
    public:
        ADTF_CLASS_ID_NAME(cMyFilter, "my_filter.filter.example.cid", "My Filter");
 
        cMyFilter()
        {
            m_oInput = adtf::filter::cSubstreamHandling(this, "input");
        }
        
        tResult Init(tInitStage eStage)
        {
            RETURN_IF_FAILED(cFilter::Init(eStage))
 
            if (eStage == StageNormal)
            {
                // this could be based on some confiugration file etc.
                m_oInput.AddSubstreamHandler("your.substream.name", [](const adtf::ucom::iobject_ptr<const adtf::streaming::ISample>& pSample)
                {
                    LOG_INFO("received a sample on substream 'your.substream.name'");
                });
            }
 
            RETURN_NOERROR;
        }
 
        tResult Shutdown(tInitStage eStage)
        {
            if (eStage == StageNormal)
            {
                m_oInput.RemoveAllHandlers();
            }
 
            return cFilter::Shutdown(eStage);
        }
 
    private:
        adtf::filter::cSubstreamHandling m_oInput;
};