From: g0dil Date: Thu, 12 Aug 2010 14:21:22 +0000 (+0000) Subject: Packets: Annotation documentation and remove SENF_PACKET_NO_COMPLEX_ANNOTATIONS X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=7c691ffe57bd1939572a94736bedf6ac3a3f7b1a;p=senf.git Packets: Annotation documentation and remove SENF_PACKET_NO_COMPLEX_ANNOTATIONS git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1680 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/senf/Packets/Mainpage.dox b/senf/Packets/Mainpage.dox index a7854d8..c428f21 100644 --- a/senf/Packets/Mainpage.dox +++ b/senf/Packets/Mainpage.dox @@ -734,8 +734,8 @@ } \endcode - Every annotation is automatically default-initialized, there is no way to query, whether a - packet holds a specific annotation -- every packet conceptually always holds all annotations. + Conceptually, all annotations always exist in every packet, there is no way to query, whether a + packet holds a specific annotation. You should use annotations economically: Every annotation type used in your program will allocate an annotation slot in \e all packet data structures. So don't use hundreds of different @@ -745,7 +745,8 @@ data together with the packet consider some other way (e.g. place the packet into another class which holds that data). - \see senf::Packet::annotation() + \see senf::Packet::annotation() \n + senf::dumpPacketAnnotationRegistry() for annotation debugging and optimization */ /** \page packet_new Defining new Packet types @@ -837,4 +838,3 @@ // mode: auto-fill // compile-command: "scons -u doc" // End: - diff --git a/senf/Packets/PacketImpl.cc b/senf/Packets/PacketImpl.cc index 9444ab7..d67a779 100644 --- a/senf/Packets/PacketImpl.cc +++ b/senf/Packets/PacketImpl.cc @@ -146,13 +146,9 @@ prefix_ void senf::detail::PacketImpl::dumpAnnotations(std::ostream & os) prefix_ void * senf::detail::PacketImpl::complexAnnotation(AnnotationRegistry::key_type key) { SENF_ASSERT( key < 0, "complexAnnotation called with invalid key"); -#ifdef SENF_PACKET_NO_COMPLEX_ANNOTATIONS - return 0; -#else return (ComplexAnnotations::size_type(-key-1) >= complexAnnotations_.size() || complexAnnotations_.is_null(-key-1)) ? 0 : complexAnnotations_[-key-1].get(); -#endif } /////////////////////////////////////////////////////////////////////////// diff --git a/senf/Packets/PacketImpl.ct b/senf/Packets/PacketImpl.ct index 93a757c..feb564d 100644 --- a/senf/Packets/PacketImpl.ct +++ b/senf/Packets/PacketImpl.ct @@ -43,14 +43,12 @@ prefix_ void * senf::detail::PacketImpl::complexAnnotation() { AnnotationRegistry::key_type key (AnnotationRegistry::lookup()); void * rv (complexAnnotation(key)); -#ifndef SENF_PACKET_NO_COMPLEX_ANNOTATIONS if (! rv) { while (complexAnnotations_.size() < ComplexAnnotations::size_type(-key)) complexAnnotations_.push_back(0); complexAnnotations_.replace(-key-1, new AnnotationRegistry::Entry()); rv = complexAnnotations_[-key-1].get(); } -#endif return rv; } diff --git a/senf/Packets/PacketImpl.hh b/senf/Packets/PacketImpl.hh index fcdd71f..5679aa2 100644 --- a/senf/Packets/PacketImpl.hh +++ b/senf/Packets/PacketImpl.hh @@ -59,6 +59,43 @@ namespace senf { */ struct ComplexAnnotation {}; + /** \brief Dump annotation registry debug information + + This function will dump debug information about all registered annotations to \a os. This + information may then be used to tune the following annotation parameters for optimal + performance: + \li \c SENF_PACKET_ANNOTATION_SLOTS (define, default 8) is the number of slots available for + fast annotations + \li \c SENF_PACKET_ANNOTATION_SLOTSIZE (define, default 16) is the maximum size of a fast + annotation in bytes + + The output includes the current parameter and has the following columns: + \li \c NAME: Annotation type name + \li \c FAST: This is 'yes', if the annotation was allocated to a fast slot. Otherwise the + annotation is managed as a slow/complex annotation + \li \c COMPLEX: This is 'yes', if the annotation inherits from ComplexAnnotation + \li \c SIZE: Size of the annotation in bytes + + Fast annotations are considerable faster than complex and slow annotations. However, only + annotations which do not need constructor or destructor calls and which may be + zero-initialized (on the memory level) are elegible as fast annotations. + + It is thus desirable to eliminate any complex and slow annotations, if possible. To optimize + the annotation system, you may take the following steps: + \li If there are reasonably sized non-complex annotations which are larger than the current + \c SENF_PACKET_ANNOTATION_SLOTSIZE value, increase this value accordingly + \li If there are more non-complex annotations with a size less than + \c SENF_PACKET_ANNOTATION_SLOTSIZE than there are available slots, increase \c + SENF_PACKET_ANNOTATION_SLOTS accordingly + \li If all fast annotations are smaller than \c SENF_PACKET_ANNOTATION_SLOTSIZE, you may + decrease that value accordingly + \li If there are fewer than \c SENF_PACKET_ANNOTATION_SLOTS fast annotations, you may + decrease that value accordingly + + \see \ref packet_usage_annotation + */ + void dumpPacketAnnotationRegistry(std::ostream & os); + namespace detail { /** \brief Internal: Packet data storage @@ -170,9 +207,7 @@ namespace detail { typedef boost::ptr_vector< boost::nullable > ComplexAnnotations; -# ifndef SENF_PACKET_NO_COMPLEX_ANNOTATIONS - ComplexAnnotations complexAnnotations_; -# endif + ComplexAnnotations complexAnnotations_; SimpleAnnotationSlot simpleAnnotations_[SENF_PACKET_ANNOTATION_SLOTS]; }; diff --git a/senf/Packets/PacketImpl.ih b/senf/Packets/PacketImpl.ih index 32ce82c..e6b7bfe 100644 --- a/senf/Packets/PacketImpl.ih +++ b/senf/Packets/PacketImpl.ih @@ -48,7 +48,6 @@ namespace senf { struct ComplexAnnotation; - void dumpPacketAnnotationRegistry(std::ostream & os); namespace detail { diff --git a/senf/config.hh b/senf/config.hh index 4dd5f02..1e1ac5f 100644 --- a/senf/config.hh +++ b/senf/config.hh @@ -96,7 +96,6 @@ namespace config { # define SENF_PACKET_ANNOTATION_SLOTSIZE 16 # endif # -//# define SENF_PACKET_NO_COMPLEX_ANNOTATIONS ///////////////////////////////hh.e//////////////////////////////////////// #endif