senf::ppi::module::Module Class Reference

Module base-class. More...

#include <senf/PPI/Module.hh>

Inherits senf::ppi::ModuleManager::Initializable, and noncopyable.

Inherited by senf::ppi::module::MonitorModule<>, senf::ppi::module::ActiveDuplicator, senf::ppi::module::ActiveFeeder, senf::ppi::module::ActiveQueueSocketSource< Packet, Connector >, senf::ppi::module::ActiveSocketSink< Writer >, senf::ppi::module::ActiveSocketSource< Reader >, senf::ppi::module::AnnotationRouter< AnnotationType >, senf::ppi::module::CloneSource, senf::ppi::module::debug::ActiveSink, senf::ppi::module::debug::ActiveSource, senf::ppi::module::debug::PassiveSink, senf::ppi::module::debug::PassiveSource, senf::ppi::module::DiscardSink, senf::ppi::module::MonitorModule< PacketType >, senf::ppi::module::PassiveJoin< PacketType >, senf::ppi::module::PassiveQueue, senf::ppi::module::PassiveQueueingSocketSink< Writer >, senf::ppi::module::PassiveQueueSocketSink< Connector >, senf::ppi::module::PassiveSocketSink< Writer >, senf::ppi::module::PriorityJoin, senf::ppi::module::QueueEthVLanFilter, senf::ppi::module::RateFilter, and senf::ppi::module::ThrottleBarrier.

Public Member Functions
virtual	~Module ()

Protected Member Functions
	Module ()
Route< connector::InputConnector, connector::OutputConnector > &	route (connector::InputConnector &input, connector::OutputConnector &output)
	Define flow information. More...
Route< connector::InputConnector, EventDescriptor > &	route (connector::InputConnector &input, EventDescriptor &output)
	Define flow information. More...
Route< EventDescriptor, connector::OutputConnector > &	route (EventDescriptor &input, connector::OutputConnector &output)
	Define flow information. More...
void	noroute (connector::Connector &connector)
	Define terminal connectors. More...
template<class Target >
void	registerEvent (EventDescriptor &descriptor, Target target)
	Register an external event. More...
ClockService::clock_type const &	time () const
	Time-stamp of the currently processing event. More...
ClockService::clock_type const &	now () const
	Current time of the currently processing event. More...
virtual void	v_init ()
	Called after module setup. More...
console::DirectoryNode &	sysConsoleDir () const
void	destroy ()

Detailed Description

Module base-class.

senf::ppi::Module is the base-class of all PPI modules. It provides the module implementation with interfaces to several PPI facilities:

• Connector management
• Flow management (routing)
• Event handling

To provide internal bookkeeping, most access to the PPI infrastructure is managed through this base class. This is an example module specification:

class SomeModule : public senf::ppi::module::Module
{
    SENF_PPI_MODULE(SomeModule);

    senf::FileHandle handle;

    // If needed, define events
    senf::ppi::IOEvent event;

public:
    // Define connectors. Any number and type of connectors may be defined. Connectors
    // must be public since they need to be accessed to connect modules with each other.
    senf::ppi::connector::PassiveInput<> input;
    senf::ppi::connector::ActiveOutput<> output;

    SomeModule(senf::FileHandle h)
      : handle ( h ),
        event  ( handle, senf::ppi::IOEvent::Read )
    {
        // Set up routing. If some connector is not routed you need to explicitly state this
        // using noroute()
        route( input, output );
        route( event, output )
            .autoThrottling( false );

        // Register event handlers
        registerEvent( event, &SomeModule::read );

        // Register passive connector handlers
        input.onRequest( &SomeModule::outputRequest );

        // If needed, you may register throttling event handlers
        output.onThrottle( &SomeModule::throttle );
        output.onUnthrottle( &SomeModule::unthrottle );
    }

    void read() {
        // Called whenever the 'handle' is readable. Read data, do processing and so
        // on. This example reads the data, puts it into an ethernet packet and sends the
        // packet out via the active output.
        output(senf::EthernetPacket::create(handle.read()))
    }

    void outputRequest() {
        // Called whenever a packet is sent into the input to. Here we just forward it to
        // the output if it is an EthernetPacket
        senf::EthernetPacket p (input().find<EthernetPacket>(senf::nothrow));
        if (p)
            output(p);
    }

    void onThrottle() {
        // Called whenever a throttle notification comes in. Here, we just disable the
        // event (which is stupid since we should just not have disabled autoThrottling on
        // the route but this is only an example which tries to be simple ...)
        event.disable();
    }

    void onUnthrottle() {
        // and for unthrottle notifications
        event.enable();
    }

    void v_init() {
        // Optional. Called after before running the module but after connections have been
        // set up. This is either directly before senf::ppi::run() or senf::ppi::init() is
        // called or, for modules created while the PPI is already running, after returning
        // from all event handlers but before going back to the event loop.
    }

};

    If your module only has a single input connector, you should call this connector \c
    input. If it has only a single output connector, you should call it \c output. This allows
    to setup connections without stating the connector explicitly (see senf::ppi::connect()).

    \see \ref ppi_modules

Definition at line 169 of file Module.hh.

Constructor & Destructor Documentation

~Module()

virtual senf::ppi::module::Module::~Module ( )

virtual

Module()

senf::ppi::module::Module::Module ( )

protected

Member Function Documentation

destroy()

void senf::ppi::module::Module::destroy ( )

protected

noroute()

void senf::ppi::module::Module::noroute ( connector::Connector &  connector )

protected

Define terminal connectors.

The noroute() member explicitly declares, that a connector is terminal and does not directly receive/forward data from/to some other connector. It is mandatory to define routing information for terminal connectors.

See the route() documentation for more on routing

Parameters

[in]

connector

Terminal connector to declare

Definition at line 114 of file Module.cc.

now()

ClockService::clock_type const& senf::ppi::module::Module::now ( ) const

protected

Current time of the currently processing event.

registerEvent()

template<class Target >

void senf::ppi::module::Module::registerEvent ( EventDescriptor &  descriptor, Target  target  )

protected

Register an external event.

The target argument may be either an arbitrary callable object or it may be a member function pointer pointing to a member function of the Module derived classed. The handler may optionally take an Argument of type Descriptor::Event const &. This object allows to access detailed information on the event delivered.

The descriptor describes the event to signal like a timer event or some type of I/O event on a file descriptor or socket.

Parameters

[in]	target	The handler to call whenever the event is signaled
[in]	descriptor	The type of event to register

Note

The real implementation has the second arguments type as an additional template parameter.

route() [1/3]

senf::ppi::Route< connector::InputConnector, connector::OutputConnector > & senf::ppi::module::Module::route ( connector::InputConnector &  input, connector::OutputConnector &  output  )

protected

Define flow information.

Using the route() and noroute() members, the information flow within the module is defined. Routing may be defined between inputs, outputs and events. The routing information is used to perform automatic throttling. The throttling behavior may however be controlled manually.

Even if no automatic throttling is desired it is essential to define the flow information for all inputs and outputs. Without flow information important internal state of the module cannot be initialized. This includes, explicitly defining terminal inputs and outputs using noroute. Event routing is optional however.

The return value may be used to alter routing parameters like throttling parameters.

Parameters

[in]	input	Data source, object which controls incoming data (connector or event)
[in]	output	Data target, object which controls outgoing data (connector or event)

Returns

Route instance describing this route

See also

Throttling

Definition at line 39 of file Module.cc.

route() [2/3]

senf::ppi::Route< connector::InputConnector, EventDescriptor > & senf::ppi::module::Module::route ( connector::InputConnector &  input, EventDescriptor &  output  )

protected

Define flow information.

Route from a connector to an event. Routing from a connector to an event defines the event as the conceptual 'receiver' of the data. This means, the event is controlling the processing of received data packets (Example: Routing from an input to an IOEvent defines, that input data will be processed whenever the event is signaled.).

This event routing allows to automatically enable/disable the event on throttling notifications.

See also

route()

Definition at line 43 of file Module.cc.

route() [3/3]

senf::ppi::RouteRoute< connector::EventDescriptor, connector::OutputConnector > & senf::ppi::module::Module::route ( EventDescriptor &  input, connector::OutputConnector &  output  )

protected

Define flow information.

Route from an event to a connector. Routing from an event to a connector defines the event as the conceptual 'source' of the data. This means, the event controls how packets are sent (Example: Routing from an IOEvent to an output defines, that output data will be generated whenever the event is signaled).

This event routing allows to automatically enable/disable the event on throttling notifications.

See also

route()

sysConsoleDir()

console::DirectoryNode& senf::ppi::module::Module::sysConsoleDir ( ) const

protected

time()

ClockService::clock_type const& senf::ppi::module::Module::time ( ) const

protected

Time-stamp of the currently processing event.

If available, this returns the scheduled time of the event.

v_init()

void senf::ppi::module::Module::v_init ( )

protectedvirtual

Called after module setup.

This member is called directly before the PPI (resumes) execution. It is called after connections have been setup before entering the PPI main loop.

You may overload this member. Your overload should always call the base-class implementation.

Implements senf::ppi::ModuleManager::Initializable.

Definition at line 120 of file Module.cc.

---

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

• Module.hh
• Module.cc