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

#include <senf/PPI/Module.hh>

Inherits
senf::ppi::ModuleManager::Initializable.

List of all members.

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 input. If it has only a single output connector, you should call it output. This allows to setup connections without stating the connector explicitly (see senf::ppi::connect()).

See also:: Modules

Definition at line 178 of file Module.hh.


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

Constructor & Destructor Documentation

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

Definition at line 66 of file Module.cci.

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

Definition at line 91 of file Module.cci.

Member Function Documentation

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

Definition at line 96 of file Module.cci.

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

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 70 of file Module.cc.

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

Current time of the currently processing event.

Definition at line 82 of file Module.cci.

template<class Target >

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

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.

Definition at line 72 of file Module.ct.

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

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()

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

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 54 of file Module.ct.

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

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

Note:: The real implementation is not provided by three overloads but by a single template member

Definition at line 50 of file Module.ct.

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

Time-stamp of the currently processing event.

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

Definition at line 76 of file Module.cci.

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

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::ModuleManager::Initializable.

Definition at line 43 of file Module.cci.

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

SENF Extensible Network Framework

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

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation