X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=PPI%2FModule.hh;h=1404a3be82549cdf9f05386b398844c211699ddb;hb=ae06fe86f16fdabb7ffb219d255444d2eb4f4f79;hp=31ef445862e86c6913e0030c8eb6e0e45269d0b5;hpb=9035ae419b1dc9dc537e00d0f7ffc4b22e19422a;p=senf.git
diff --git a/PPI/Module.hh b/PPI/Module.hh
index 31ef445..1404a3b 100644
--- a/PPI/Module.hh
+++ b/PPI/Module.hh
@@ -56,23 +56,16 @@ namespace module {
The PPI provided general purpose modules can be grouped into several categories
\li \ref io_modules receive external data or forward packets out of the PPI
- \li \ref sourcesink_modules generate or absorb packets internally
\li \ref routing_modules forward packets within the network
\li \ref adapter_modules are used to connect incompatible connectors to each other
\todo Implement Spliters: PassiveSplitter, PrioritySplitter, CloneSplitter
*/
- /** \defgroup io_modules Input/Output Modules
+ /** \defgroup io_modules Source/Sink Modules
- Input/Output Modules receive data from external sources or forward data from the PPI to
- outside targets.
- */
-
- /** \defgroup sourcesink_modules Source/Sink Modules
-
- Source and Sink modules generate or absorb packets internally. In contrast to \ref
- io_modules, they do not communicate outside the PPI.
+ Source and Sink modules generate or absorb packets in some way: Reading data from a file
+ descriptor, discarding packets etc.
*/
/** \defgroup routing_modules Routing Modules
@@ -125,7 +118,7 @@ namespace module {
.autoThrottling( false );
// Register event handlers
- registerEvent( &SomeModule::read, event );
+ registerEvent( event, &SomeModule::read );
// Register passive connector handlers
input.onRequest( &SomeModule::outputRequest );
@@ -168,6 +161,8 @@ namespace module {
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
*/
class Module
: boost::noncopyable
@@ -187,37 +182,61 @@ namespace module {
///< Define flow information
/**< Using the route() and noroute() members, the
information flow within the module is defined. Routing
- may be specified either between inputs, outputs and
- events. The routing information is used to perform
- automatic throttling. The throttling behavior may
- however be controlled manually.
+ 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
- vital to define the flow information for all inputs and
- outputs. Without flow information important
+ 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 however is optional.
+ routing is optional however.
The return value may be used to alter routing
parameters like throttling parameters.
-
- \param[in] source Data source, object which controls
+
+ \param[in] input Data source, object which controls
incoming data (connector or event)
- \param[in] target Data target, object which controls
+ \param[in] output Data target, object which controls
outgoing data (connector or event)
- \returns Route instance describing this route */
+ \returns Route instance describing this route
+ \see \ref ppi_throttling
+ \note The real implementation is not provided by three
+ overloads but by a single template member */
Route &
route(connector::InputConnector & input, EventDescriptor & output);
///< Define flow information
- /**< \see \ref route() */
+ /**< 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 \ref route() */
Route &
route(EventDescriptor & input, connector::OutputConnector & output);
///< Define flow information
- /**< \see \ref route() */
+ /**< 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 \ref route() */
#endif
void noroute(connector::Connector & connector); ///< Define terminal connectors
@@ -231,8 +250,12 @@ namespace module {
\param[in] connector Terminal connector to declare */
- template
- void registerEvent(Target target, Descriptor & descriptor);
+#ifndef DOXYGEN
+ template
+ void registerEvent(Descriptor & descriptor, Target target);
+#else
+ template
+ void registerEvent(EventDescriptor & descriptor, Target target);
///< Register an external event
/**< The \a target argument may be either an arbitrary
callable object or it may be a member function pointer
@@ -242,14 +265,16 @@ namespace module {
allows to access detailed information on the event
delivered.
- The \a descriptor describes the event to signal. This
-
- may be a timer event or some type of I/O event on a
- file descriptor or socket.
+ The \a descriptor describes the event to signal like a
+ timer event or some type of I/O event on a file
+ descriptor or socket.
\param[in] target The handler to call whenever the
event is signaled
- \param[in] descriptor The type of event to register */
+ \param[in] descriptor The type of event to register
+ \note The real implementation has the second arguments
+ type as an additional template parameter. */
+#endif
ClockService::clock_type time() const; ///< Time-stamp of the currently processing event
/**< If available, this returns the scheduled time of the