Utils/Logger: Target examples\nPackets: Relax annotation type restrictions

[senf.git] / Packets / Packet.hh

diff --git a/Packets/Packet.hh b/Packets/Packet.hh
index 58264f8..ac77eed 100644 (file)
--- a/Packets/Packet.hh
+++ b/Packets/Packet.hh
@@ -316,9 +316,63 @@ namespace senf {
 
         ///\name Annotations
         ///@{
-        
+
         template <class Annotation>
-        Annotation & annotation();
+        Annotation & annotation();      ///< Get packet annotation
+                                        /**< This member will retrieve an arbitrary packet
+                                             annotation. Every annotation is identified by a unique
+                                             \a Annotation type. This type should \e always be a \c
+                                             struct.
+
+                                             \code
+                                             struct MyAnnotation {
+                                                 int value;
+                                             };
+
+                                             senf::Packet p (...);
+                                            
+                                             p.annotation<MyAnnotation>().value = 1;
+                                             \endcode
+                                             
+                                             Annotations are shared by all headers / interpreters
+                                             within a single packet chain.
+
+                                             If an annotation is \e not a POD type (more
+                                             specifically, if it's constructor or destructor is not
+                                             trivial including base classes and members), the \a
+                                             Annotation type \e must inherit from
+                                             senf::ComplexAnnotation. Failing to follow this rule
+                                             will result in undefined behavior and will probably
+                                             lead to a program crash.
+
+                                             \code
+                                             struct MyStringAnnotation : senf::ComplexAnnotation {
+                                                 std::string value;
+                                             };
+                                             \endcode
+                                             (This type is not POD since \c std::string is not POD)
+
+                                             \see \ref packet_usage_annotation
+
+                                             \implementation The annotation system is implemented
+                                                 quite efficiently since annotations are stored
+                                                 within a packet embedded vector of fixed size (the
+                                                 size is determined automatically at runtime by the
+                                                 number of different annotations
+                                                 used). Additionally, non-complex small annotations
+                                                 require no additional memory management (\c new /
+                                                 \c delete).
+                                             
+                                             \idea Pool the annotation vectors: In the destructor
+                                                 swap the vector into a vector graveyard (swapping
+                                                 two vectors is an O(1) no allocation operation). In
+                                                 the constructor, if there is a vector in the
+                                                 graveyard, swap it in from there. Of course, it
+                                                 would be better to do away with the vector and just
+                                                 allocate the space together with the packet but
+                                                 that looks quite complicated to do ... especially
+                                                 considering that the packetimpl itself uses a pool.
+                                          */
 
         ///@}