///\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), 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
+
+ \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.
+ */
///@}