X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=PPI%2FMainpage.dox;h=fc16dab14b63e722a23aff30aac5d5ae0ad81e3f;hb=61dc3812717cdc89fa2402006d4009236b72dc8f;hp=0acd574374075c9337bdc4d360d04d33d7d48043;hpb=9936320904d4d5bbf6dd91cf7efc6fbc08ad462c;p=senf.git diff --git a/PPI/Mainpage.dox b/PPI/Mainpage.dox index 0acd574..fc16dab 100644 --- a/PPI/Mainpage.dox +++ b/PPI/Mainpage.dox @@ -1,6 +1,8 @@ -// Copyright (C) 2007 -// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS) -// Kompetenzzentrum fuer Satelitenkommunikation (SatCom) +// $Id$ +// +// Copyright (C) 2007 +// Fraunhofer Institute for Open Communication Systems (FOKUS) +// Competence Center NETwork research (NET), St. Augustin, GERMANY // Stefan Bund // // This program is free software; you can redistribute it and/or modify @@ -24,7 +26,7 @@ PPI application is built by combining processing modules in a very flexible manner. \image html scenario.png Target Scenario - + The PPI concept is built around some key concepts \li The PPI is based on processing \ref ppi_packets. It does not handle stream oriented @@ -35,7 +37,7 @@ \li Data flow throughout the network is governed via flexible automatic or manual \ref ppi_throttling (throttle notifications). \li Modules may register additional external \ref ppi_events (file descriptor events or timers). - + The PPI thereby builds on the facilities provided by the other components of the SENF framework. The target scenario above depicts a diffserv capable UDLR/ULE router including performance optimizations for TCP traffic (PEP). This router is built by combining several @@ -45,44 +47,32 @@ PPI Example Application: RateStuffer \n \ref senf::ppi::module "Modules" \n - \ref senf::ppi::connector "Connectors" \n + \ref senf::ppi::connector "Connectors and Jacks" \n \ref event_group */ /** \page ppi_overview PPI Overview and Concepts -
-
Contents
-
    -
  1. \ref ppi_design
    2. -
  2. \ref ppi_packets
    3. -
  3. \ref ppi_modules
    4. -
  4. \ref ppi_connectors
    5. -
  5. \ref ppi_connections
    6. -
  6. \ref ppi_throttling
    7. -
  7. \ref ppi_events
    8. -
  8. \ref ppi_run
    9. -
  9. \ref ppi_flows
    10. -
-
+ \autotoc \section ppi_design Design considerations The PPI interface is designed to be as simple as possible. It provides sane defaults for all configurable parameters to simplify getting started. It also automates all resource management. The throttling infrastructure handles blocking conditions (like input exhaustion) - automatically. + automatically. \section ppi_packets Packets The PPI processes packets and uses the Packet - library to handle them. All packets are passed around as generic \ref senf::Packet - references, the PPI does not enforce any packet type restrictions. + library to handle them. All packets are internally passed around as generic \ref + senf::Packet references, however connectors may optionally be defined as sending or receiving + packets of a specific type only. \section ppi_modules Modules - A module is represented by a class derived from senf::ppi::Module. Each module has several - components: + A module is represented by a class derived from senf::ppi::module::Module. Each module has + several components: \li It may have any number of \ref ppi_connectors (inputs and outputs) \li Each module declares flow information which details the route packets take within the @@ -101,8 +91,8 @@ Of these modules, normally only the application modules need to be implemented since the library provides an extensive set of reusable modules. - - The following example module declares three \ref ppi_connectors "Connectors": \c payload, + + The following example module declares three \ref ppi_connectors "Connectors": \c payload, \c stuffing and \c output. These connectors are defined as \e public data members so they can be accessed from the outside. This is important as we will see below. @@ -115,9 +105,9 @@ senf::ppi::IntervalTimer timer_; public: - senf::ppi::connector::ActiveInput payload; - senf::ppi::connector::ActiveInput stuffing; - senf::ppi::connector::ActiveOutput output; + senf::ppi::connector::ActiveInput<> payload; + senf::ppi::connector::ActiveInput<> stuffing; + senf::ppi::connector::ActiveOutput<> output; RateStuffer(unsigned packetsPerSecond) : timer_(1000u, packetsPerSecond) @@ -146,10 +136,10 @@ The module processing is very simple: Whenever a timer tick arrives a packet is sent. If the \c payload input is ready (see \ref ppi_throttling), a payload packet is sent, otherwise a stuffing packet is sent. The module will therefore provide a constant stream of packets at a fixed rate - on \c output (see the - RateStuffer example application + on \c output (see the + RateStuffer example application for a slightly different approach) - + An example module to generate the stuffing packets could be \code @@ -158,7 +148,7 @@ { SENF_PPI_MODULE(CopyPacketGenerator); public: - senf::ppi::connector::PassiveOutput output; + senf::ppi::connector::PassiveOutput<> output; CopyPacketGenerator(Packet template) : template_ (template) @@ -182,7 +172,7 @@ \see senf::ppi::module::Module \section ppi_connectors Connectors - + The input and output attachment points of a module are called connectors. Each connector may be active or passive. This gives us 4 types of connectors: @@ -210,6 +200,9 @@ To provide this flexibility, all input connectors incorporate a packet queue. This queue is exposed to the module and allows the module to optionally process packets in batches. + Connectors take an optional template argument which allows to specify the type of packet this + connector sends or received. This template arguments defaults to \ref senf::Packet. + \see \ref senf::ppi::connector \section ppi_connections Connections @@ -219,25 +212,29 @@ To make use of the modules, they have to be instantiated and connections have to be created between its connectors. It is possible to connect any pair of input/output connectors as long as one of them is active and the other is passive. - + It is possible to connect two active or passive connectors with each other using a special adaptor module (senf::ppi::module::PassiveQueue or senf::ppi::module::ActiveFeeder respectively). + + Additionally, the connectors must be type-compatible: Either one (or both) of the connectors + must be untyped (they accept arbitrary senf::Packet's, the optional tempalte argument is empty), + or they both accept the same type of packet. This check is performed at runtime. - To complete our simplified example: Lets connet senf::ppi::module::ActiveSocketReader and + To complete our simplified example: Lets connect senf::ppi::module::ActiveSocketReader and senf::ppi::module::PassiveSocketWriter to our example module: \code RateStuffer rateStuffer (10); - senf::Packet stuffingPacket = senf::DataPacket::create(...); + senf::Packet stuffingPacket = senf::DataPacket::create(...); CopyPacketGenerator generator (stuffingPacket); senf::UDPv4ClientSocketHandle inputSocket (1111); - senf::ppi::module::ActiveSocketReader udpInput (inputSocket); + senf::ppi::module::ActiveSocketSource<> udpInput (inputSocket); senf::UDPv4ClientSocketHandle outputSocket ("2.3.4.5:2222"); - senf::ppi::module::PassiveSocketWriter udpOutput (outputSocket); + senf::ppi::module::PassiveSocketSink<> udpOutput (outputSocket); senf::ppi::module::PassiveQueue adaptor; @@ -252,7 +249,7 @@ This application will read udp-packets coming in on port 1111 and will forward them to port 2222 on host 2.3.4.5 with a fixed rate of 10 packets / second. - + We start out by instantiating the necessary modules. Then the connections between these modules are set up by successively connecting each output connector to an input connector. As can be seen, the name of the connector can be left of if it is named \c output or \c input @@ -304,15 +301,15 @@ disabled, see \ref senf::ppi::connector::ActiveConnector) to be called when a throttle notification is received. The callback may then handle the notification however it sees fit, for example by manually throttling some passive connector (see \ref - senf::ppi::connector::PassiveConnector). + senf::ppi::connector::PassiveConnector). - To enable/disable automatic throttling, the \ref senf::ppi::module::Module::route() command + To enable/disable automatic throttling, the \ref senf::ppi::module::Module::route() command returns a reference to a \ref senf::ppi::Route instance. If this route is \e forwarding route, - (that is, of the connectors is passive and the other is active), the return value will be + (that is, of the connectors is passive and the other is active), the return value will be derived from \ref senf::ppi::ForwardingRoute which provides members to control the throttle notification forwarding. - - \see + + \see senf::ppi::module::Module \n senf::ppi::Route @@ -329,11 +326,11 @@ perform the call. This is handled by the Scheduler, which is wrapped by the event classes. - + All events are derived from senf::ppi::EventDescriptor. The base class allows to enable and disable the event. Each type of event will take descriptor specific constructor arguments to describe the event to be generated. Events are declared as (private) data members of the - module and are then registered using senf::ppi::module::Module::registerEvent(). + module and are then registered using senf::ppi::module::Module::registerEvent(). Each event when signaled is described by an instance of the descriptor specific \e descriptorType \c ::Event class. This instance will hold the event specific information (like @@ -382,7 +379,7 @@ \section ppi_flows Information Flow The above description conceptually introduces three different flow levels: - + \li The data flow is, where the packets are flowing. This flow always goes from output to input connector. \li The execution flow describes the flow of execution from one module to another. This @@ -395,7 +392,7 @@ Within a module, the different flow levels are defined differently depending on the type of flow: - + \li The data flow is defined by how data is processed. The different event and connector callbacks will pass packets around and thereby define the data flow \li Likewise, the execution flow is defined parallel to the data flow (however possible @@ -412,7 +409,7 @@ */ /** \page ppi_implementation Implementation Notes - + \section processing Data Processing The processing in the PPI is driven by events. Without events nothing will happen. When @@ -446,7 +443,7 @@ Every module manages a collection of all it's connectors and every connector has a reference to it's containing module. In addition, every connector maintains a collection of all it's routing - targets. + targets. All this data is initialized via the routing statements. This is, why \e every connector must appear in at least one routing statement: These statements will as a side effect initialize the @@ -457,9 +454,9 @@ instance. This simplifies the PPI usage considerably. The same is true for the connectors: Since they know the containing module, they can explicitly bind unbound member function pointers to the instance. - + \section ppi_random_notes Random implementation notes - + Generation of throttle notifications: Backward throttling notifications are automatically generated (if this is not disabled) whenever the input queue is non-empty \e after the event handler has finished processing. Forward throttling notifications are not generated @@ -468,10 +465,31 @@ \section ppi_classdiagram Class Diagram - \image html classes.png +
+ \ref senf::ppi::connector::PassiveConnector + \ref senf::ppi::EventManager + \ref senf::ppi::connector::ActiveOutput + \ref senf::ppi::connector::ActiveInput + \ref senf::ppi::RouteBase + \ref senf::ppi::Route + \ref (some module) + \ref senf::ppi::EventImplementation + \ref senf::ppi::module::Module + \ref senf::ppi::connector::Connector + \ref senf::ppi::connector::PassiveOutput + \ref senf::ppi::detail::EventBindingBase + \ref senf::ppi::connector::InputConnector + \ref senf::ppi::detail::RouteImplementation + \ref senf::ppi::connector::OutputConnector + \ref senf::ppi::connector::ActiveConnector + \ref senf::ppi::detail::EventBinding + \ref senf::ppi::EventDescriptor + \ref senf::ppi::connector::PassiveInput +
+ \htmlonly classes \endhtmlonly */ - + // Local Variables: // mode: c++ // fill-column: 100