// $Id$
//
-// Copyright (C) 2007
-// Fraunhofer Institute for Open Communication Systems (FOKUS)
-// Competence Center NETwork research (NET), St. Augustin, GERMANY
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
namespace connector {
/** \namespace senf::ppi::connector
- \brief Connector classes
+ \brief Connector classes
A connector has two independent properties
- \li it may be \e active or \e passive
- \li it may be an \e input or an \e output
-
+ - it may be \e active or \e passive
+ - it may be an \e input or an \e output
+
\e Active connectors are activated from within the module, \e passive connectors are
signaled by the external framework. \e Input modules receive packets, \e output modules send
packets.
All passive connectors call some onRequest callback whenever I/O needs to be performed. All
input modules possess a packet queue.
- We therefore have 4 connector types:
- \li senf::ppi::connector::ActiveInput
- \li senf::ppi::connector::ActiveOutput
- \li senf::ppi::connector::PassiveInput
- \li senf::ppi::connector::PassiveOutput.
+ We therefore have 4 connector types:
+ - senf::ppi::connector::ActiveInput
+ - senf::ppi::connector::ActiveOutput
+ - senf::ppi::connector::PassiveInput
+ - senf::ppi::connector::PassiveOutput.
Connectors are declared as module data members and are then externally connected to other
modules.
- \see
+ The connectors each take an optional template argument. If this argument is specified, it
+ must be the type of packet expected or sent on this connector. If it is not specified,
+ packets will be passed using the generic Packet handle.
+
+ \code
+ class IpFilter : public senf::ppi::module::Module
+ {
+ SENF_PPI_MODULE(SomeModule);
+
+ public:
+ senf::ppi::connector::ActiveInput<senf::EthernetPacket> input;
+ senf::ppi::connector::PassiveOutput<senf::IpPacket> output;
+
+ IpFilter() {
+ route(input, output);
+ input.onRequest(&IpFilter::onRequest);
+ }
+
+ private:
+ void onRequest() {
+ // 'input()' will return a senf::EthernetPacket packet handle
+ try { output( input().find<IpPacket>() ); }
+ catch (senf::InvalidPacketChainException & ex) { ; }
+ }
+ };
+ \endcode
+
+ \see
senf::ppi::module::Module \n
- senf::ppi::connect()
+ senf::ppi::connect() \n
\ref ppi_connectors
*/
of connector (output or input) the respective throttling is called forward or backward
throttling.
- Passive connectors always handle two throttling states:
-
- \li The \e native throttling state is set manually by the module. It is the throttling state
+ Passive connectors always handle two throttling states:
+
+ - The \e native throttling state is set manually by the module. It is the throttling state
originating in the current module
- \li The \e forwarded throttling state is the state as it is received by throttling
+ - The \e forwarded throttling state is the state as it is received by throttling
notifications
The accumulative throttling state is generated by combining all sub-states.
*/
- class PassiveConnector
+ class PassiveConnector
: public virtual Connector
{
public:
is a pointer-to-member to a member of the class which
holds this input. In the second case, the pointer will
automatically be bound to the containing instance.
-
+
\param[in] handler Handler to call, whenever an I/O
operation is to be performed. */
-
+
bool throttled() const; ///< Get accumulative throttling state
bool nativeThrottled() const; ///< Get native throttling state
void throttle(); ///< Set native throttling
void unthrottle(); ///< Revoke native throttling
-
+
ActiveConnector & peer() const;
protected:
notifications. These notifications should then either be processed by the module or be
forwarded to other connectors.
*/
- class ActiveConnector
+ class ActiveConnector
: public virtual Connector
{
typedef ppi::detail::Callback<>::type Callback;
insertion/deletion but I believe that list is just to expensive since every packet will
be added to the queue before it can be processed.
*/
- class InputConnector
+ class InputConnector
: public virtual Connector
{
typedef std::deque<Packet> Queue;
protected:
InputConnector();
-
+
private:
void enqueue(Packet p);
-
+
virtual void v_requestEvent();
virtual void v_enqueueEvent();
virtual void v_dequeueEvent();
friend class OutputConnector;
};
-
+
/** \brief Output connector base-class
-
+
An output connector sends out packets. It may be either an ActiveConnector or a
PassiveConnector. An output connector does \e not have an built-in queueing, it relies on
the queueing of the connected input.
*/
- class OutputConnector
+ class OutputConnector
: public virtual Connector
{
public:
protected:
OutputConnector();
};
-
+
/** \brief Combination of PassiveConnector and InputConnector
- The GenericPassiveInput automatically controls the connectors throttling state using a queueing
- discipline. The standard queueing discipline is ThresholdQueueing, which throttles the
- connection whenever the queue length reaches the high threshold and unthrottles the
+ The GenericPassiveInput automatically controls the connectors throttling state using a
+ queueing discipline. The standard queueing discipline is ThresholdQueueing, which throttles
+ the connection whenever the queue length reaches the high threshold and unthrottles the
connection when the queue reaches the low threshold. The default queueing discipline is
<tt>ThresholdQueueing(1,0)</tt> which will throttle the input whenever the queue is
non-empty.
*/
- class GenericPassiveInput
+ class GenericPassiveInput
: public PassiveConnector, public InputConnector,
public safe_bool<GenericPassiveInput>
{
public:
- GenericPassiveInput();
-
GenericActiveOutput & peer() const;
bool boolean_test() const; ///< \c true, if ! empty()
void qdisc(QDisc const & disc); ///< Change the queueing discipline
/**< The queueing discipline is a class which provides the
QueueingDiscipline interface.
-
+
\param[in] disc New queueing discipline */
+ protected:
+ GenericPassiveInput();
+
private:
void v_enqueueEvent();
void v_dequeueEvent();
void connect(GenericActiveInput & target); ///< Internal: Use senf::ppi::connect() instead
friend class GenericActiveInput;
+
+ protected:
+ GenericPassiveOutput();
+
};
/** \brief Combination of ActiveConnector and InputConnector
void request(); ///< request more packets without dequeuing any packet
+ protected:
+ GenericActiveInput();
+
private:
void v_requestEvent();
};
bool boolean_test() const; ///< \c true if peer() is ! throttled()
void connect(GenericPassiveInput & target); ///< Internal: Use senf::ppi::connect() instead
+
+ protected:
+ GenericActiveOutput();
+
};
-# define TypedConnector(Name, Mixin, dir) \
+#ifndef DOXYGEN
+
+# define TypedConnector_Input read
+# define TypedConnector_Output write
+# define TypedConnector(type, dir) \
template <class PacketType> \
- class Name \
- : public Generic ## Name, detail::TypedInputMixin<Name<PacketType>, PacketType> \
+ class type ## dir \
+ : public Generic ## type ## dir, \
+ private detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType> \
{ \
- typedef detail::TypedInputMixin<Name<PacketType>, PacketType> mixin; \
+ typedef detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType> mixin; \
public: \
using mixin::operator(); \
- using mixin:: dir ; \
+ using mixin::TypedConnector_ ## dir ; \
+ private: \
+ friend class detail::Typed ## dir ## Mixin<type ## dir <PacketType>, PacketType>; \
}; \
template <> \
- class Name <Packet> \
- : public Generic ## Name \
+ class type ## dir <Packet> : public Generic ## type ## dir \
{}
- TypedConnector(PassiveInput, TypedInputMixin, read);
- TypedConnector(PassiveOutput, TypedOutputMixin, write);
- TypedConnector(ActiveInput, TypedInputMixin, read);
- TypedConnector(ActiveOutput, TypedOutputMixin, write);
+ TypedConnector( Passive, Input );
+ TypedConnector( Passive, Output );
+ TypedConnector( Active, Input );
+ TypedConnector( Active, Output );
# undef TypedConnector
+# undef TypedConnector_Input
+# undef TypedConnector_Output
+
+#else
+
+ /** \brief Connector actively reading packets
+
+ The ActiveInput connector template reads data actively from a connected module. This class
+ is completely implemented via it's base-class, GenericActiveInput, the only difference is
+ that read packets are returned as \a PacketType instead of generic senf::Packet references.
+
+ \see GenericActiveInput \n
+ senf::ppi::connector
+ */
+ template <class PacketType=Packet>
+ class ActiveInput : public GenericActiveInput
+ {
+ public:
+ PacketType operator()(); ///< Read packet
+ /**< \throws std::bad_cast, if the connector receives a
+ Packet which is not of type \a PacketType.
+ \returns newly read packet reference. */
+ PacketType read(); ///< Alias for operator()
+ };
+
+ /** \brief Connector passively receiving packets
+
+ The PassiveInput connector template receives packets sent to it from a connected
+ module. This class is completely implemented via it's base-class, GenericPassiveInput, the
+ only difference is that read packets are returned as \a PacketType instead of generic
+ senf::Packet references.
+
+ \see GenericPassiveInput \n
+ senf::ppi::connector
+ */
+ template <class PacketType=Packet>
+ class PassiveInput : public GenericPassiveInput
+ {
+ public:
+ PacketType operator()(); ///< Read packet
+ /**< \throws std::bad_cast, if the connector receives a
+ Packet which is not of type \a PacketType.
+ \returns newly read packet reference. */
+ PacketType read(); ///< Alias for operator()
+ };
+
+ /** \brief Connector actively sending packets
+
+ The ActiveOutput connector template sends data actively to a connected module. This class is
+ completely implemented via it's base-class, GenericActiveOutput, the only difference is that
+ it only sends packets of type \a PacketType.
+
+ \see GenericActiveOutput \n
+ senf::ppi::connector
+ */
+ template <class PacketType=Packet>
+ class ActiveOutput : public GenericActiveOutput
+ {
+ public:
+ operator()(PacketType packet); ///< Send out a packet
+ write(PacketType packet); ///< Alias for operator()
+ };
+
+ /** \brief Connector passively providing packets
+
+ The PassiveOutput connector template provides data passively to a connected module whenever
+ signaled. This class is completely implemented via it's base-class, GenericPassiveOutput, the
+ only difference is that it only sends packets of type \a PacketType.
+
+ \see GenericPassiveOutput \n
+ senf::ppi::connector
+ */
+ template <class PacketType=Packet>
+ class PassiveOutput : public GenericPassiveOutput
+ {
+ public:
+ operator()(PacketType packet); ///< Send out a packet
+ write(PacketType packet); ///< Alias for operator()
+ };
+
+#endif
}}}
projects / senf.git / blobdiff