Changeset 8853

Timestamp:

Aug 21, 2011, 11:18:20 PM (13 years ago)

Author:

landauf

Message:

documented the remaining code of the output system
created a build unit for the output system

Location:

code/branches/output/src/libraries/util

Files:

• CMakeLists.txt (modified) (1 diff)
• Output.h (modified) (1 diff)
• output/BaseWriter.cc (modified) (11 diffs)
• output/BaseWriter.h (modified) (5 diffs)
• output/CMakeLists.txt (added)
• output/OutputDefinitions.h (modified) (2 diffs)
• output/SubcontextOutputListener.cc (modified) (5 diffs)
• output/SubcontextOutputListener.h (modified) (2 diffs)

code/branches/output/src/libraries/util/CMakeLists.txt

@@ -39 +39 @@
   SignalHandler.cc
   StringUtils.cc
-  output/OutputStream.cc
-  output/OutputManager.cc
-  output/OutputListener.cc
-  output/BaseWriter.cc
-  output/ConsoleWriter.cc
-  output/LogWriter.cc
-  output/MemoryWriter.cc
-  output/SubcontextOutputListener.cc
 )
+
+ADD_SUBDIRECTORY(output)
 
 ORXONOX_ADD_LIBRARY(util

code/branches/output/src/libraries/util/Output.h

@@ -45 +45 @@
 
     Each orxonox::OutputListener can define a mask of desired levels and
-    contexts, to receive only a part of the output. A derivative of
-    orxonox::BaseWriter is able to define these masks through config values
-    and to filter specific subcontexts.
+    contexts, to receive only a part of the output. Instances of
+    orxonox::SubcontextOutputListener are even able to filter sub-contexts.
+    A derivative of orxonox::BaseWriter is able to define these levels and
+    contexts through config values.
 
     @attention

code/branches/output/src/libraries/util/output/BaseWriter.cc

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @brief Implementation of the BaseWriter class.
+*/
+
 #include "BaseWriter.h"
 
@@ -33 +38 @@
 namespace orxonox
 {
+    /**
+        @brief Constructor: Initializes the config-values.
+    */
     BaseWriter::BaseWriter(const std::string& name, bool bRegister) : SubcontextOutputListener(bRegister)
     {
@@ -46 +54 @@
     }
 
+    /**
+        @brief Destructor.
+    */
     BaseWriter::~BaseWriter()
     {
     }
 
+    /**
+        @brief This function is inherited from OutputListener, each message is split into lines and sent to printLine().
+    */
     void BaseWriter::output(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines)
     {
@@ -59 +73 @@
     }
 
+    /**
+        @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
+    */
     void BaseWriter::setLevelMax(OutputLevel max)
     {
@@ -65 +82 @@
     }
 
+    /**
+        @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
+    */
     void BaseWriter::setAdditionalContextsLevelMax(OutputLevel max)
     {
@@ -71 +91 @@
     }
 
+    /**
+        @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
+    */
     void BaseWriter::changedConfigurableLevel()
     {
@@ -76 +99 @@
     }
 
+    /**
+        @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
+    */
     void BaseWriter::changedConfigurableAdditionalContextsLevel()
     {
@@ -81 +107 @@
     }
 
+    /**
+        @brief Called if the config-vector of accepted contexts has changed, updates the masks in SubcontextOutputListener.
+    */
     void BaseWriter::changedConfigurableAdditionalContexts()
     {
@@ -86 +115 @@
         std::set<const OutputContextContainer*> sub_contexts;
 
+        // iterate over all strings in the config-vector
         for (size_t i = 0; i < this->configurableAdditionalContexts_.size(); ++i)
         {
             const std::string& full_name = this->configurableAdditionalContexts_[i];
 
+            // split the name into main-name and sub-name (if given; otherwise sub-name remains empty). both names are separated by ::
             std::string name = full_name;
             std::string subname;
@@ -100 +131 @@
             }
 
+            // get the context defined by this name
             const OutputContextContainer& context = OutputManager::getInstance().registerContext(name, subname);
 
+            // if the context is a sub-context, insert it to the set of sub-contexts. Otherwise add it's mask to the mask of main-contexts.
             if (context.sub_id == context::no_subcontext)
                 main_contexts |= context.mask;
@@ -108 +141 @@
         }
 
+        // pass main-contexts and sub-contexts to SubcontextOutputListener
         this->setAdditionalContextsMask(main_contexts);
         this->setAdditionalSubcontexts(sub_contexts);

code/branches/output/src/libraries/util/output/BaseWriter.h

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @ingroup Output
+    @brief Declaration of the BaseWriter class, the base of all output writers.
+*/
+
 #ifndef _BaseWriter_H__
 #define _BaseWriter_H__
@@ -35 +41 @@
 namespace orxonox
 {
+    /**
+        @brief BaseWriter is an output listener and makes the accepted output levels and contexts configurable.
+
+        All output writers like ConsoleWriter and LogWriter are inherited from
+        this class. BaseWriter itself inherits from SubcontextOutputListener.
+        It adds helper functions to configure the accepted levels and contexts.
+
+        The levels are not fully configurable, only the "max" form is allowed
+        (which means that it's only possible to define a maximum level, not
+        the full mask).
+
+        Contexts are defined by a vector of strings, each context is defined
+        by it's name. Sub-contexts have the form \a "main-name::sub-name", i.e.
+        their name is concatenated with :: in between.
+
+        Each instance of BaseWriter needs a name to generate distinguishable
+        config values.
+
+        Received output messages are split into lines and sent line by line to
+        the virtual printLine() function. Each line has a prepended prefix
+        which describes the level and context of the output.
+    */
     class _UtilExport BaseWriter : public SubcontextOutputListener
     {
@@ -44 +72 @@
             void setAdditionalContextsLevelMax(OutputLevel max);
 
+            /// @brief Returns the name of this instance.
             const std::string& getName() const
                 { return this->name_; }
 
+            /// Config value, used to define the maximum output level (independent of contexts)
             int configurableMaxLevel_;
+            /// @brief Returns the name of the config value which defines the maximum output level (independent of contexts).
             inline std::string getConfigurableMaxLevelName() const
                 { return this->name_ + "Level"; }
 
+            /// Config value, used to define the maximum output level of additional context
             int configurableAdditionalContextsMaxLevel_;
+            /// @brief Returns the name of the config value which defines the maximum output level of additional context.
             inline std::string getConfigurableAdditionalContextsMaxLevelName() const
                 { return this->name_ + "AdditionalContextsLevel"; }
 
+            /// Config vector, used to define the additional contexts (and sub-contexts)
             std::vector<std::string> configurableAdditionalContexts_;
+            /// @brief Returns the name of the config vector which defines the additional contexts (and sub-contexts)
             inline std::string getConfigurableAdditionalContextsName() const
                 { return this->name_ + "AdditionalContexts"; }
@@ -63 +98 @@
             void changedConfigurableAdditionalContexts();
 
+            /// Returns the (static) name of the section wherein the config-values are defined.
             static inline std::string getConfigurableSectionName()
                 { return "Output"; }
@@ -70 +106 @@
 
         private:
-            virtual void printLine(const std::string& line, OutputLevel level) = 0;
+            virtual void printLine(const std::string& line, OutputLevel level) = 0; ///< Pure virtual function, gets called for each line of output together with a prefix which describes level and context of the output.
 
-            void setLevelRange(OutputLevel min, OutputLevel max);
-            void setLevelMask(OutputLevel mask);
+            void setLevelRange(OutputLevel min, OutputLevel max);                   ///< Inherited function, overwritten as private because it is not supported by the config-value
+            void setLevelMask(OutputLevel mask);                                    ///< Inherited function, overwritten as private because it is not supported by the config-value
 
-            void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max);
-            void setAdditionalContextsLevelMask(OutputLevel mask);
+            void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max); ///< Inherited function, overwritten as private because it is not supported by the config-value
+            void setAdditionalContextsLevelMask(OutputLevel mask);                  ///< Inherited function, overwritten as private because it is not supported by the config-value
 
-            std::string name_;
+            std::string name_; ///< The name of this instance, used to generate unique config-values
     };
 }

code/branches/output/src/libraries/util/output/OutputDefinitions.h

@@ -58 +58 @@
     share the context mask of their main-context. This allows contexts with
     more descriptive names (e.g. input::keyboard) and they can be filtered
-    individually by derivatives of orxonox::BaseWriter.
+    individually by derivatives of orxonox::SubcontextOutputListener.
 */
 #define REGISTER_OUTPUT_SUBCONTEXT(name, subname) \
@@ -160 +160 @@
                 REGISTER_OUTPUT_SUBCONTEXT(misc, script);
             }
-
         }
     }

code/branches/output/src/libraries/util/output/SubcontextOutputListener.cc

@@ -27 +27 @@
  */
 
+/**
+    @file
+    @brief Implementation of the SubcontextOutputListener interface.
+*/
+
 #include "SubcontextOutputListener.h"
 
 namespace orxonox
 {
+    /**
+        @brief Constructor, initializes the context masks.
+    */
     SubcontextOutputListener::SubcontextOutputListener(bool bRegister) : OutputListener(bRegister)
     {
@@ -37 +45 @@
     }
 
+    /**
+        @brief Destructor.
+    */
     SubcontextOutputListener::~SubcontextOutputListener()
     {
     }
 
+    /**
+        @brief Overwritten implementation of the function defined by OutputListener.
+
+        Contexts defined with this function are accepted independent of the
+        sub-context. The "final" mask of additional contexts is defined by the
+        combination of this mask and the masks of all accepted sub-contexts.
+    */
     void SubcontextOutputListener::setAdditionalContextsMask(OutputContextMask mask)
     {
@@ -48 +66 @@
     }
 
+    /**
+        @brief Defines the set of accepted sub-contexts.
+
+        The masks of sub-contexts in this set are added to the mask of
+        additional contexts, but output is only accepted if the exact
+        sub-context exists in this set.
+    */
     void SubcontextOutputListener::setAdditionalSubcontexts(const std::set<const OutputContextContainer*>& subcontexts)
     {
@@ -53 +78 @@
         this->subcontexts_.clear();
 
+        // compose the mask of subcontexts and build the set of sub-context-IDs
         for (std::set<const OutputContextContainer*>::const_iterator it = subcontexts.begin(); it != subcontexts.end(); ++it)
         {
@@ -63 +89 @@
 
     /**
-        @brief Returns true if this listener accepts output of the given level and context, based on the levels, contexts masks, and sub-contexts.
+        @brief Returns true if this listener accepts output of the given level and context, based on the levels and contexts masks, as well as the set of accepted sub-contexts.
     */
     bool SubcontextOutputListener::acceptsOutput(OutputLevel level, const OutputContextContainer& context) const

code/branches/output/src/libraries/util/output/SubcontextOutputListener.h

@@ -44 +44 @@
 namespace orxonox
 {
+    /**
+        @brief This class extends the basic OutputListener interface and adds the ability to filter sub-contexts.
+
+        Defining additional contexts with setAdditionalContextsMask() enables
+        all sub-contexts of these additional contexts. To accept only some
+        particular sub-contexts, setAdditionalSubcontexts() has to be used.
+        Note that this requires a set, since a mask is not possible with
+        sub-contexts.
+
+        The "final" context mask which will be seen by OutputManager is the
+        combination of all regular contexts plus the masks of all sub-contexts.
+
+        @remark
+        It would have been possible to implement filtering of sub-contexts
+        directly in OutputListener and even to make OutputManager aware of
+        sub-contexts. This would reduce the amount of unnecessarily generated
+        output, but also increase the complexity of the checks whether some
+        output is needed.
+        On the other hand, filtering of sub-contexts makes the whole concept
+        more complicated, as it adds another mask and a set. So to keep it
+        clean and simple I figured it's best to put sub-context filtering into
+        a seaparate class.
+    */
     class _UtilExport SubcontextOutputListener : public OutputListener
     {
@@ -56 +79 @@
 
         private:
-            OutputContextMask subcontextsCheckMask_;
-            OutputContextMask subcontextsNoCheckMask_;
-            std::set<OutputContextSubID> subcontexts_;
+            OutputContextMask subcontextsCheckMask_;    ///< All contexts defined by this mask need to be checked whether they are accepted by the set of sub-contexts
+            OutputContextMask subcontextsNoCheckMask_;  ///< All contexts defined by this mask don't need to be checked since we accept all sub-contexts
+            std::set<OutputContextSubID> subcontexts_;  ///< The set of accepted sub-contexts
     };
 }