From: g0dil Date: Thu, 19 Jul 2007 23:09:27 +0000 (+0000) Subject: Packets: Add short documentation for most internal classes X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=d084c02e4914da4fa1a4098a33d704f69e8bdedd;p=senf.git Packets: Add short documentation for most internal classes Packets: Document DataPacket, safe_data_iterator and exceptions Packets: Move bundle documentation out of the Packets documentation Scheduler: Make test more robust (add sleep ...) Move all local dictionary words into senf.dict git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@325 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/PPI/Mainpage.dox b/PPI/Mainpage.dox index 2020f02..040811f 100644 --- a/PPI/Mainpage.dox +++ b/PPI/Mainpage.dox @@ -401,4 +401,3 @@ // mode: auto-fill // End: -// LocalWords: callbacks diff --git a/Packets/DataPacket.hh b/Packets/DataPacket.hh index 0d4b615..33c2d63 100644 --- a/Packets/DataPacket.hh +++ b/Packets/DataPacket.hh @@ -32,10 +32,23 @@ ///////////////////////////////hh.p//////////////////////////////////////// namespace senf { - + + /** \brief Internal: Packet type of DataPacket + + \internal + */ struct DataPacketType : public PacketTypeBase {}; + + /** \brief Generic payload-only packet + + DataPacket is a simple generic packet with just a payload of uninterpreted data. This is the + packet used whenever no more specific packet type can be found for a sub-packet (e.g. as the + payload data of a UDP packet) + + \ingroup packet_module + */ typedef ConcretePacket DataPacket; } @@ -58,3 +71,4 @@ namespace senf { // ispell-local-dictionary: "american" // compile-command: "scons -u test" // End: + diff --git a/Packets/DefaultBundle/DefaultBundle.dox b/Packets/DefaultBundle/DefaultBundle.dox index ad6977c..e902443 100644 --- a/Packets/DefaultBundle/DefaultBundle.dox +++ b/Packets/DefaultBundle/DefaultBundle.dox @@ -18,18 +18,19 @@ // Free Software Foundation, Inc., // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -/** \defgroup protocolbundles Protocol Bundles +/** \mainpage The Default Bundle - Each protocol bundle provides a collection of related concrete packet classes for a group of - related protocols. + The default bundle combines a set of basic low level protocols like Ethernet or IP. You can find + the list of implemented protocols at \ref protocolbundle_default (see the list of typedefs) */ -/** \defgroup protocolbundle_default The Default Bundle +/** \defgroup protocolbundle_default Protocols of the default bundle - The default bundle combines a set of basic low level protocols like Ethernet or IP. Find the - list of packet types implemented below under 'Typedefs'. + Each protocol consists of several objects - \ingroup protocolbundles + \li The packet \c typedef symbol. This is the only object explicitly accessed from the outside + \li The associated parser object. This is, where the field names are documented + \li The internal packet type object */ @@ -44,6 +45,3 @@ // mode: auto-fill // End: -// LocalWords: Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de -// LocalWords: Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios IP -// LocalWords: defgroup protocolbundles protocolbundle ingroup dil diff --git a/Packets/DefaultBundle/Doxyfile b/Packets/DefaultBundle/Doxyfile new file mode 100644 index 0000000..2e8aec2 --- /dev/null +++ b/Packets/DefaultBundle/Doxyfile @@ -0,0 +1,6 @@ +@INCLUDE = "$(TOPDIR)/doclib/Doxyfile.global" + +PROJECT_NAME = libPackets/DefaultBundle +TAGFILES = "$(TOPDIR)/Utils/doc/Utils.tag" "$(TOPDIR)/Packets/doc/Packets.tag" +GENERATE_TAGFILE = doc/DefaultBundle.tag +INPUT = . diff --git a/Packets/DefaultBundle/SConscript b/Packets/DefaultBundle/SConscript index f096a68..eaf1982 100644 --- a/Packets/DefaultBundle/SConscript +++ b/Packets/DefaultBundle/SConscript @@ -11,4 +11,7 @@ SENFSCons.StandardTargets(env) SENFSCons.Object(env, target = 'DefaultBundle', sources=sources, LIBS = ['Packets', 'Socket', 'Utils']) +SENFSCons.Lib(env, library = 'Packets_DefaultBundle', sources = sources[0], + LIBS = ['Packets', 'Socket', 'Utils']) +SENFSCons.Doxygen(env) diff --git a/Packets/Doxyfile b/Packets/Doxyfile index 86ce327..931a153 100644 --- a/Packets/Doxyfile +++ b/Packets/Doxyfile @@ -3,6 +3,7 @@ PROJECT_NAME = libPackets TAGFILES = "$(TOPDIR)/Utils/doc/Utils.tag" GENERATE_TAGFILE = doc/Packets.tag -INPUT = . DefaultBundle MPEG_DVBBundle +#INPUT = . DefaultBundle MPEG_DVBBundle +INPUT = . -EXAMPLE_PATH = . DefaultBundle +#EXAMPLE_PATH = . DefaultBundle diff --git a/Packets/MPEG_DVBBundle/Doxyfile b/Packets/MPEG_DVBBundle/Doxyfile new file mode 100644 index 0000000..1727026 --- /dev/null +++ b/Packets/MPEG_DVBBundle/Doxyfile @@ -0,0 +1,6 @@ +@INCLUDE = "$(TOPDIR)/doclib/Doxyfile.global" + +PROJECT_NAME = libPackets/MPEG_DVBBundle +TAGFILES = "$(TOPDIR)/Utils/doc/Utils.tag" "$(TOPDIR)/Packets/doc/Packets.tag" +GENERATE_TAGFILE = doc/MPEG_DVBBundle.tag +INPUT = . diff --git a/Packets/MPEG_DVBBundle/SConscript b/Packets/MPEG_DVBBundle/SConscript index fde1e8c..57d258d 100644 --- a/Packets/MPEG_DVBBundle/SConscript +++ b/Packets/MPEG_DVBBundle/SConscript @@ -11,4 +11,7 @@ SENFSCons.StandardTargets(env) SENFSCons.Object(env, target = 'MPEG_DVBBundle', sources=sources, LIBS = ['Packets', 'Socket', 'Utils']) +SENFSCons.Lib(env, library = 'Packets_MPEG_DVBBundle', sources = sources[0], + LIBS = ['Packets', 'Socket', 'Utils']) +SENFSCons.Doxygen(env) diff --git a/Packets/Mainpage.dox b/Packets/Mainpage.dox index f62651f..0855250 100644 --- a/Packets/Mainpage.dox +++ b/Packets/Mainpage.dox @@ -128,6 +128,17 @@ a detailed discussion see the respective reference documentation. */ +/** \defgroup protocolbundles Protocol Bundles + + Each protocol bundle provides a collection of related concrete packet classes for a group of + related protocols: + + \li DefaultBundle: Some basic + default protocols: Ethernet, Ip, TCP, UDP + \li MPEG_DVBBundle: MPEG and DVB + protocols + */ + // Local Variables: // mode: c++ @@ -139,8 +150,3 @@ // compile-command: "scons -u doc" // End: -// LocalWords: mainpage SENF packetparser protocolbundles protocolbundle IPv4 -// LocalWords: udp endcode li senf EthernetPacket eth IpV createAfter ip std -// LocalWords: ethernet UDPPacket DataPacket ttl INet MACAddress nothrow prev -// LocalWords: PacketSocketHandle InvalidPacketChainException findNext noinit -// LocalWords: tt TruncatedPacketException const cerr Ooops hh diff --git a/Packets/Packet.hh b/Packets/Packet.hh index fabd6a4..afdfe7d 100644 --- a/Packets/Packet.hh +++ b/Packets/Packet.hh @@ -599,12 +599,3 @@ namespace senf { // comment-column: 40 // End: -// LocalWords: defgroup li html png STL ConcretePacket PacketInterpreterBase -// LocalWords: PacketInterpreter PacketImpl OtherPacket EthernetPacket param -// LocalWords: EthernetPacketType PacketData packetparser nothrow senf prev -// LocalWords: InvalidPacketChainException findNext findPrev parseNextAs tt -// LocalWords: PacketType SomePacketType createAfter createBefore noinit href -// LocalWords: PacketTypeBase TruncatedPacketException http www org Institut -// LocalWords: Fraunhofer fuer offene Kommunikationssysteme FOKUS SatCom Bund -// LocalWords: Kompetenzzentrum Satelitenkommunikation berlios de hh -// LocalWords: addtogroup Structors PacketType dil PacketType's diff --git a/Packets/PacketData.hh b/Packets/PacketData.hh index 8d94d9c..9ebe32e 100644 --- a/Packets/PacketData.hh +++ b/Packets/PacketData.hh @@ -140,9 +140,25 @@ namespace senf { class PacketParserBase; + /** \brief Invalid packet data access + + This exception is signaled whenever an operation tries to access an out-of-bounds data + byte. If the packet has been implemented correctly, this signals a malformed packet. + */ struct TruncatedPacketException : public std::exception { virtual char const * what() const throw() { return "truncated packet"; } }; + /** \brief Re-validating data iterator + + This class is a wrapper around a PacketData::iterator instance. It will revalidate the + iterator on every access. This keeps the iterator valid even when the data container is + resized and thereby possibly relocated. The iterator will always point to the byte at the + same offset from the packets beginning. If data is inserted before this iterators position, + the data pointed to will of course change. + + For this to work, the safe_data_iterator must be initialized with the container to which the + iterator belongs. After this initialization it can be used like any other iterator. + */ class safe_data_iterator : public boost::iterator_facade< safe_data_iterator, PacketData::value_type, @@ -152,18 +168,29 @@ namespace senf { public: typedef PacketData::size_type size_type; - safe_data_iterator(); - explicit safe_data_iterator(PacketData & data); + safe_data_iterator(); ///< Make uninitialized iterator + explicit safe_data_iterator(PacketData & data); + ///< Construct iterator only setting the data container safe_data_iterator(PacketData & data, PacketData::iterator i); + ///< Initialize iterator to given position explicit safe_data_iterator(PacketParserBase const & parser); + ///< Initialize iterator from parser + /**< The iterator will point to the parsers start + position. */ - safe_data_iterator & operator=(PacketData::iterator i); + safe_data_iterator & operator=(PacketData::iterator i); ///< Assign iterator + /**< The iteator \a i must be from the container wo which \c + this iterator has been initialized. */ safe_data_iterator & operator=(PacketParserBase const & parser); - operator PacketData::iterator() const; + ///< Assign iterator from parser + /**< The iterator will point to the parser start + position. */ + + operator PacketData::iterator() const; ///< Convert to iterator - bool boolean_test() const; + bool boolean_test() const; ///< Check, if iterator is initialized - PacketData & data() const; + PacketData & data() const; ///< Access data container private: friend class boost::iterator_core_access; @@ -204,7 +231,3 @@ namespace senf { // comment-column: 40 // End: -// LocalWords: Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de -// LocalWords: Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios dil -// LocalWords: PacketData hh STL PacketInterpreterBase PacketInterpreter -// LocalWords: ingroup Structors diff --git a/Packets/PacketImpl.hh b/Packets/PacketImpl.hh index 516d272..5ec43f6 100644 --- a/Packets/PacketImpl.hh +++ b/Packets/PacketImpl.hh @@ -36,6 +36,15 @@ namespace senf { namespace detail { + /** \brief Internal: Packet data storage + + \internal + + This is the class holding the packet data and the interpreter chain. All manipulations of + the packet data are performed via the interface exported here. This is very important, since + PacketImpl will update the interpreters (that is the vector indices stored therein) whenever + the data is changed. + */ class PacketImpl : boost::noncopyable, public pool_alloc_mixin @@ -92,9 +101,14 @@ namespace detail { void erase(PacketData * self, iterator first, iterator last); void clear(PacketData * self); - // The Guard will keep the PacketImpl instance alive during a members execution time - // It the refcount should drop to 0, PacketImpl will be deleted after the member - // has completed executing. + /** \brief Internal: Keep PacketImpl instance alive + + \internal + + The Guard will keep the PacketImpl instance alive during a members execution time + It the refcount should drop to 0, PacketImpl will be deleted after the member + has completed executing. + */ struct Guard { Guard(PacketImpl * impl); ~Guard(); @@ -108,7 +122,6 @@ namespace detail { void eraseInterpreters(interpreter_list::iterator b, interpreter_list::iterator e); void updateIterators(PacketData * self, iterator pos, difference_type n); - }; }} @@ -132,3 +145,4 @@ namespace detail { // compile-command: "scons -u test" // comment-column: 40 // End: + diff --git a/Packets/PacketInterpreter.hh b/Packets/PacketInterpreter.hh index 878de5b..2cf35d9 100644 --- a/Packets/PacketInterpreter.hh +++ b/Packets/PacketInterpreter.hh @@ -42,7 +42,12 @@ namespace senf { template class PacketInterpreter; - /** \brief + /** \brief Internal: Base packet interpreter class + + \internal + + This is the base class for the persistent interpreter. This class encapsulates all the + functionality accessible via the packet handle, most handle operations are just forwarded. */ class PacketInterpreterBase : protected PacketData, @@ -70,6 +75,14 @@ namespace senf { enum Prepend_t { Prepend }; enum NoInit_t { noinit }; + /** \brief Internal: Abstract packet factory + + \internal + + This abstract class provides an abstract packet factory interface. It allows to call + almost any one of the create / createAfter / createBefore static PacketInterpreter + without static information on the type of packet to create. + */ struct Factory { virtual ~Factory(); @@ -169,7 +182,7 @@ namespace senf { ptr appendClone(detail::PacketImpl * impl, range r); public: - // Need this for g++ < 4.0. Since PacketInterpreter is not publically visible, it should not + // Need this for g++ < 4.0. Since PacketInterpreter is not publicly visible, it should not // be a real problem to make impl() public here using PacketData::impl; @@ -201,7 +214,13 @@ namespace senf { friend class detail::packet::test::TestDriver; }; - /** \brief Concrete packet interpreter + /** \brief Internal: Concrete packet interpreter + + \internal + + Instantiations of this class build the interpreter chain. This class is accessed by the + packet handles. It provides the packet-type specific functionality in addition to the + interface defined in the PacketInterpreterBase class. \see PacketTypeBase for the \a PacketType interface */ @@ -301,6 +320,12 @@ namespace senf { // factory + /** \brief Internal: Implementation of abstract factory interface + + \internal + + Implements the abstract factory interface for \a PacketType + */ struct FactoryImpl : public Factory { // Create completely new packet @@ -346,6 +371,11 @@ namespace senf { friend class FactoryImpl; }; + /** \brief Invalid packet chain operation + + This exception signals an invalid operation on the chain like trying to find a non-existent + chain member and other similar error conditions. + */ struct InvalidPacketChainException : public std::exception { virtual char const * what() const throw() { return "invalid packet chain"; } }; diff --git a/Packets/PacketParser.hh b/Packets/PacketParser.hh index b963955..631bf10 100644 --- a/Packets/PacketParser.hh +++ b/Packets/PacketParser.hh @@ -516,6 +516,8 @@ namespace senf { # define SENF_PACKET_PARSER_DEFINE_FIXED_FIELDS_OFFSET(offset,fields) \ SENF_PACKET_PARSER_I_DEFINE_FIXED_FIELDS(offset,fields) + /** \brief Default parser parsing nothing + */ struct VoidPacketParser : public PacketParserBase { @@ -599,13 +601,3 @@ namespace senf { // comment-column: 40 // End: -// LocalWords: templated PacketParser defgroup packetparser PacketParsers li -// LocalWords: EthernetParser ethertype UInt senf PacketParserBase tt -// LocalWords: struct FooParser const init endcode ingroup param SomeParser -// LocalWords: ethernet DefaultBundle EthernetPacket hh EthVLan UIntField CFI -// LocalWords: VLanId OverlayField cfi vlanId accessor defaultInit bitfield -// LocalWords: SomePacket SimpleVectorSizer packetparsermacros Fraunhofer std -// LocalWords: hideinitializer Institut fuer offene Kommunikationssysteme STL -// LocalWords: FOKUS Kompetenzzentrum Satelitenkommunikation SatCom Bund cerr -// LocalWords: berlios dil Structors someField someVector someOtherField -// LocalWords: TruncatedPacketException diff --git a/Packets/PacketRegistry.hh b/Packets/PacketRegistry.hh index ef1fa26..172a233 100644 --- a/Packets/PacketRegistry.hh +++ b/Packets/PacketRegistry.hh @@ -193,6 +193,10 @@ packet of which the key is requested static Registry & registry(); }; + /** \brief Entry not found in registry + + This exception is signaled whenever a throwing lookup operation fails. + */ struct PacketTypeNotRegisteredException : public std::exception { virtual char const * what() const throw() { return "packet type not registered"; } }; @@ -218,10 +222,3 @@ packet of which the key is requested // comment-column: 40 // End: -// LocalWords: PacketRegistry hh dil Fraunhofer Institut fuer offene FOKUS de -// LocalWords: Kommunikationssysteme Kompetenzzentrum Satelitenkommunikation -// LocalWords: SatCom Bund stefan bund fokus fraunhofer Ethertype IP struct -// LocalWords: SomeTag endcode senf SomePacket registerPacket ingroup param -// LocalWords: registerSomePacket RegistrationProxy namespace PacketType key -// LocalWords: registerPacketType ConcretePacket PacketTypeNotRegistered href -// LocalWords: http www org html diff --git a/Packets/PacketRegistry.ih b/Packets/PacketRegistry.ih index 4043362..7ea93c8 100644 --- a/Packets/PacketRegistry.ih +++ b/Packets/PacketRegistry.ih @@ -35,7 +35,9 @@ namespace senf { namespace detail { - ///\internal + /** \brief Internal + \internal + */ template struct PkReg_EntryImpl : public PkReg_Entry @@ -43,7 +45,9 @@ namespace detail { virtual Packet::factory_t factory() const; }; - ///\internal + /** \brief Internal + \internal + */ template class PacketRegistryImpl : private boost::noncopyable diff --git a/Packets/PacketType.hh b/Packets/PacketType.hh index 03af113..5d34507 100644 --- a/Packets/PacketType.hh +++ b/Packets/PacketType.hh @@ -321,6 +321,8 @@ namespace senf { static void init (Packet p); }; +# ifndef DOXYGEN + template class PacketTypeMixin { @@ -330,6 +332,8 @@ namespace senf { static void init (Packet p); }; +# endif + } ///////////////////////////////hh.e//////////////////////////////////////// @@ -352,11 +356,3 @@ namespace senf { // comment-column: 40 // End: -// LocalWords: Fraunhofer Institut fuer offene Kommunikationssysteme FOKUS de -// LocalWords: Kompetenzzentrum Satelitenkommunikation SatCom Bund berlios dil -// LocalWords: PacketType struct SomePacketType senf PacketTypeBase initSize -// LocalWords: ConcretePacket init initHeadSize nextPacketRange NextPacket os -// LocalWords: nextPacketType std ostream endcode ingroup VoidPacketParser Ok -// LocalWords: tt li OtherPacketType Mixin mixin SimplePacketType typeField -// LocalWords: PacketTypeMixin SomeRegistryTag SomePacketParser nextPacketKey -// LocalWords: hh diff --git a/Packets/PacketTypes.hh b/Packets/PacketTypes.hh index 68fa471..f710fc7 100644 --- a/Packets/PacketTypes.hh +++ b/Packets/PacketTypes.hh @@ -45,6 +45,10 @@ namespace detail { namespace packet { + /** \brief Internal: Tempalte typedef for used smart pointer + + \internal + */ template struct smart_pointer { typedef boost::intrusive_ptr ptr_t; diff --git a/Scheduler/Scheduler.test.cc b/Scheduler/Scheduler.test.cc index 0e17869..f0055a5 100644 --- a/Scheduler/Scheduler.test.cc +++ b/Scheduler/Scheduler.test.cc @@ -1,3 +1,4 @@ + // $Id$ // // Copyright (C) 2006 @@ -240,6 +241,7 @@ BOOST_AUTO_UNIT_TEST(scheduler) BOOST_CHECK_NO_THROW( Scheduler::instance().remove(handle,Scheduler::EV_WRITE) ); event = Scheduler::EV_NONE; + sleep(1); BOOST_CHECK_NO_THROW( Scheduler::instance().process() ); BOOST_CHECK_EQUAL( event, Scheduler::EventId(Scheduler::EV_READ|Scheduler::EV_HUP) ); BOOST_REQUIRE_EQUAL( size, 2 ); diff --git a/project.el b/project.el index 95d7cb4..7211395 100644 --- a/project.el +++ b/project.el @@ -77,4 +77,6 @@ is ignored (Those are the file local variables and local words)." ;; Better set this here than in the file variables since the setting ;; is only valid if project.el is loaded ... +(set (make-local-variable 'ispell-personal-dictionary) + (expand-file-name "senf.dict" ccide-project-root)) (flyspell-cc-mode) diff --git a/senf.dict b/senf.dict new file mode 100644 index 0000000..2ad10da --- /dev/null +++ b/senf.dict @@ -0,0 +1,141 @@ +accessor +addtogroup +berlios +bitfield +bund +Bund +callbacks +cerr +cfi +CFI +ConcretePacket +const +createAfter +createBefore +DataPacket +de +DefaultBundle +defaultInit +defgroup +dil +endcode +eth +ethernet +EthernetPacket +EthernetPacketType +EthernetParser +ethertype +Ethertype +EthVLan +findNext +findPrev +fokus +FOKUS +FooParser +fraunhofer +Fraunhofer +fuer +hh +hideinitializer +href +html +http +impl +INet +ingroup +init +initHeadSize +initSize +Institut +InvalidPacketChainException +ip +IP +IpV +IPv4 +key +Kommunikationssysteme +Kompetenzzentrum +li +MACAddress +mainpage +mixin +Mixin +namespace +NextPacket +nextPacketKey +nextPacketRange +nextPacketType +noinit +nothrow +offene +Ok +Ooops +org +os +ostream +OtherPacket +OtherPacketType +OverlayField +PacketData +PacketImpl +PacketInterpreter +PacketInterpreterBase +packetparser +PacketParser +PacketParserBase +packetparsermacros +PacketParsers +PacketRegistry +PacketSocketHandle +PacketType +PacketTypeBase +PacketTypeMixin +PacketTypeNotRegistered +PacketType's +param +parseNextAs +png +prev +protocolbundle +protocolbundles +refcount +registerPacket +registerPacketType +registerSomePacket +RegistrationProxy +rerference +SatCom +Satelitenkommunikation +senf +SENF +SimplePacketType +SimpleVectorSizer +someField +someOtherField +SomePacket +SomePacketParser +SomePacketType +SomeParser +SomeRegistryTag +SomeTag +someVector +std +stefan +STL +struct +structors +Structors +templated +TruncatedPacketException +tt +ttl +typeField +udp +UDP +UDPPacket +UInt +UIntField +vlanId +VLanId +VoidPacketParser +www