FKIE Message Filters
Improved filters for processing ROS messages
Public Types | Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
fkie_message_filters::UserFilter< Inputs, Outputs > Class Template Reference

Generic filter with user-defined callback function. More...

#include <fkie_message_filters/user_filter.h>

Inheritance diagram for fkie_message_filters::UserFilter< Inputs, Outputs >:
Inheritance graph
[legend]
Collaboration diagram for fkie_message_filters::UserFilter< Inputs, Outputs >:
Collaboration graph
[legend]

Public Types

using CallbackFunction = FilterCB< Outputs... >
 Callback function type. More...
 
using Input = IO< Inputs... >
 Grouped input types. More...
 
using Output = IO< Outputs... >
 Grouped output types. More...
 
using ProcessingFunction = std::function< void(const Inputs &..., const CallbackFunction &)>
 Processing function type. More...
 

Public Member Functions

Connection connect_to_sink (Sink< Outputs... > &dst) noexcept
 Connect this source to a sink. More...
 
Connection connect_to_source (Source< Inputs... > &src) noexcept
 Connect this sink to a source. More...
 
void disconnect_from_all_sinks () noexcept
 Disconnect from all connected sinks. More...
 
void disconnect_from_all_sources () noexcept
 Disconnect from all connected sources. More...
 
virtual void reset () noexcept
 Reset filter state. More...
 
void set_processing_function (const ProcessingFunction &f) noexcept
 Set the user-defined processing function. More...
 

Static Public Attributes

static constexpr std::size_t NUM_INPUTS = sizeof...(Inputs)
 Number of input arguments.
 
static constexpr std::size_t NUM_OUTPUTS = sizeof...(Outputs)
 Number of output arguments.
 

Protected Member Functions

void receive (const Inputs &... in) override
 Process incoming data. More...
 
void send (const Outputs &... out)
 Pass data to all connected sinks. More...
 

Detailed Description

template<class... Inputs, class... Outputs>
class fkie_message_filters::UserFilter< Inputs, Outputs >

Generic filter with user-defined callback function.

You can implement your own filter logic and integrate it with the filter pipeline. For this, you need to define your own function that takes the Inputs and a CallbackFunction as arguments. The function will be called by the generic filter, and expects you to feed back the processed data using the callback function. Typically, your code will look similar to this:

namespace mf = fkie_message_filters;
using InBuffer = mf::Buffer<T1, T2>;
using OutBuffer = mf::Buffer<T3, T4>;
using MyFilter = mf::UserFilter<InBuffer::Output, OutBuffer::Input>;
void my_processing_func(const T1& t1, const T2& t2, const MyFilter::CallbackFunction& cb)
{
// Process the inputs t1 and t2 and prepare the outputs t3 and t4
T3 t3;
T4 t4;
// ...
// Feed the outputs back into the filter pipeline
cb(t3, t4);
}

Set up your filter pipeline like this:

InBuffer in;
MyFilter flt;
OutBuffer out;
flt.set_processing_function(my_processing_func);
mf::chain(in, flt, out);

In your processing function, you can call the callback function as often as you want, or even not at all. There is no requirement that each input produces exactly one output. When you have no output at all, or the output is the same as the input, you should consider the SimpleUserFilter instead, which is easier to set up.

The filter will throw a std::bad_function_call exception if it is invoked without a user-defined processing function.

Member Typedef Documentation

◆ CallbackFunction

template<class... Inputs, class... Outputs>
using fkie_message_filters::UserFilter< Inputs, Outputs >::CallbackFunction = FilterCB<Outputs...>

Callback function type.

This is the signature of the callback function pointer your processing function will receive.

◆ Input

template<typename... Inputs>
using fkie_message_filters::Sink< Inputs >::Input = IO<Inputs...>
inherited

Grouped input types.

This type can be used to define sources with matching types.

◆ Output

template<typename... Outputs>
using fkie_message_filters::Source< Outputs >::Output = IO<Outputs...>
inherited

Grouped output types.

This type can be used to define sinks with matching types.

◆ ProcessingFunction

template<class... Inputs, class... Outputs>
using fkie_message_filters::UserFilter< Inputs, Outputs >::ProcessingFunction = std::function<void(const Inputs&..., const CallbackFunction&)>

Processing function type.

This can be any user-defined function and will be called to process incoming data. The results are expected be returned via the callback function.

Member Function Documentation

◆ connect_to_sink()

template<typename... Outputs>
Connection fkie_message_filters::Source< Outputs >::connect_to_sink ( Sink< Outputs... > &  dst)
noexceptinherited

Connect this source to a sink.

Can be called multiple times to connect multiple sinks; in that case, the sinks receive data in the same order as they have been connected. This function does basically the same thing as Sink::connect_to_source(), only from the opposite point of view.

  • dst the sink that is to be connected
Returns
a connection object that can be used to monitor or sever the created connection
Exceptions
Does not throw any exceptions.

◆ connect_to_source()

template<typename... Inputs>
Connection fkie_message_filters::Sink< Inputs >::connect_to_source ( Source< Inputs... > &  src)
noexceptinherited

Connect this sink to a source.

Can be called multiple times to connect multiple sources; in that case, the sink receives data from all connected sources. This function does basically the same thing as Source::connect_to_sink(), only from the opposite point of view.

  • src the source that is to be connected
Returns
a connection object that can be used to monitor or sever the created connection
Exceptions
Does not throw any exceptions.

◆ disconnect_from_all_sinks()

template<typename... Outputs>
void fkie_message_filters::Source< Outputs >::disconnect_from_all_sinks ( )
noexceptinherited

Disconnect from all connected sinks.

Severs the connection to all sinks, turning the send() method into a no-op.

Exceptions
Does not throw any exceptions.

◆ disconnect_from_all_sources()

template<typename... Inputs>
void fkie_message_filters::Sink< Inputs >::disconnect_from_all_sources ( )
noexceptinherited

Disconnect from all connected sources.

Severs the connection to all sources. The receive() method will not be called any more.

Exceptions
Does not throw any exceptions.

◆ receive()

template<class... Inputs, class... Outputs>
void fkie_message_filters::UserFilter< Inputs, Outputs >::receive ( const Inputs &...  in)
overrideprotectedvirtual

Process incoming data.

Derived classes need to override this method to handle all data that is to be consumed by the sink.

Exceptions
Depends on the implementation.

Implements fkie_message_filters::Sink< Inputs >.

◆ reset()

virtual void fkie_message_filters::FilterBase::reset ( )
inlinevirtualnoexceptinherited

Reset filter state.

For stateful filters, this method resets the internal state as if the filter had just been created. Existing connections to sources and sinks are unaffected.

The default implementation does nothing.

Exceptions
Does not throw any exceptions.

Reimplemented in fkie_message_filters::Buffer< Inputs >, fkie_message_filters::Buffer< Inputs... >, fkie_message_filters::TfFilter< Inputs >, fkie_message_filters::TfFilter< Inputs... >, fkie_message_filters::Combiner< PolicyTmpl, IOs >, fkie_message_filters::Sequencer< Inputs >, and fkie_message_filters::Sequencer< Inputs... >.

◆ send()

template<typename... Outputs>
void fkie_message_filters::Source< Outputs >::send ( const Outputs &...  out)
protectedinherited

Pass data to all connected sinks.

  • out data
Exceptions
Does not throw any exceptions, but will propagate uncaught exceptions from filter callbacks.

◆ set_processing_function()

template<class... Inputs, class... Outputs>
void fkie_message_filters::UserFilter< Inputs, Outputs >::set_processing_function ( const ProcessingFunction f)
noexcept

Set the user-defined processing function.

You must call this method before the filter gets invoked with incoming data.

Exceptions
Does not throw any exceptions.

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