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 (file)
--- 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 (file)
--- 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 (file)
--- 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<Annotation>());
     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<Annotation>());
         rv = complexAnnotations_[-key-1].get();
     }
-#endif
     return rv;
 }
 

diff --git a/senf/Packets/PacketImpl.hh b/senf/Packets/PacketImpl.hh
index fcdd71f..5679aa2 100644 (file)
--- 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<AnnotationRegistry::EntryBase> >
             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 (file)
--- 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 (file)
--- 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