Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 8853 for code/branches/output


Ignore:
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:
1 added
7 edited

Legend:

Unmodified
Added
Removed

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

    r8850 r8853  
    3939  SignalHandler.cc
    4040  StringUtils.cc
    41   output/OutputStream.cc
    42   output/OutputManager.cc
    43   output/OutputListener.cc
    44   output/BaseWriter.cc
    45   output/ConsoleWriter.cc
    46   output/LogWriter.cc
    47   output/MemoryWriter.cc
    48   output/SubcontextOutputListener.cc
    4941)
     42
     43ADD_SUBDIRECTORY(output)
    5044
    5145ORXONOX_ADD_LIBRARY(util

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

    r8848 r8853  
    4545
    4646    Each orxonox::OutputListener can define a mask of desired levels and
    47     contexts, to receive only a part of the output. A derivative of
    48     orxonox::BaseWriter is able to define these masks through config values
    49     and to filter specific subcontexts.
     47    contexts, to receive only a part of the output. Instances of
     48    orxonox::SubcontextOutputListener are even able to filter sub-contexts.
     49    A derivative of orxonox::BaseWriter is able to define these levels and
     50    contexts through config values.
    5051
    5152    @attention

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

    r8850 r8853  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the BaseWriter class.
     32*/
     33
    2934#include "BaseWriter.h"
    3035
    … …  
    3338namespace orxonox
    3439{
     40    /**
     41        @brief Constructor: Initializes the config-values.
     42    */
    3543    BaseWriter::BaseWriter(const std::string& name, bool bRegister) : SubcontextOutputListener(bRegister)
    3644    {
    … …  
    4654    }
    4755
     56    /**
     57        @brief Destructor.
     58    */
    4859    BaseWriter::~BaseWriter()
    4960    {
    5061    }
    5162
     63    /**
     64        @brief This function is inherited from OutputListener, each message is split into lines and sent to printLine().
     65    */
    5266    void BaseWriter::output(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines)
    5367    {
    … …  
    5973    }
    6074
     75    /**
     76        @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
     77    */
    6178    void BaseWriter::setLevelMax(OutputLevel max)
    6279    {
    … …  
    6582    }
    6683
     84    /**
     85        @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
     86    */
    6787    void BaseWriter::setAdditionalContextsLevelMax(OutputLevel max)
    6888    {
    … …  
    7191    }
    7292
     93    /**
     94        @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
     95    */
    7396    void BaseWriter::changedConfigurableLevel()
    7497    {
    … …  
    7699    }
    77100
     101    /**
     102        @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
     103    */
    78104    void BaseWriter::changedConfigurableAdditionalContextsLevel()
    79105    {
    … …  
    81107    }
    82108
     109    /**
     110        @brief Called if the config-vector of accepted contexts has changed, updates the masks in SubcontextOutputListener.
     111    */
    83112    void BaseWriter::changedConfigurableAdditionalContexts()
    84113    {
    … …  
    86115        std::set<const OutputContextContainer*> sub_contexts;
    87116
     117        // iterate over all strings in the config-vector
    88118        for (size_t i = 0; i < this->configurableAdditionalContexts_.size(); ++i)
    89119        {
    90120            const std::string& full_name = this->configurableAdditionalContexts_[i];
    91121
     122            // split the name into main-name and sub-name (if given; otherwise sub-name remains empty). both names are separated by ::
    92123            std::string name = full_name;
    93124            std::string subname;
    … …  
    100131            }
    101132
     133            // get the context defined by this name
    102134            const OutputContextContainer& context = OutputManager::getInstance().registerContext(name, subname);
    103135
     136            // 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.
    104137            if (context.sub_id == context::no_subcontext)
    105138                main_contexts |= context.mask;
    … …  
    108141        }
    109142
     143        // pass main-contexts and sub-contexts to SubcontextOutputListener
    110144        this->setAdditionalContextsMask(main_contexts);
    111145        this->setAdditionalSubcontexts(sub_contexts);

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

    r8850 r8853  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the BaseWriter class, the base of all output writers.
     33*/
     34
    2935#ifndef _BaseWriter_H__
    3036#define _BaseWriter_H__
    … …  
    3541namespace orxonox
    3642{
     43    /**
     44        @brief BaseWriter is an output listener and makes the accepted output levels and contexts configurable.
     45
     46        All output writers like ConsoleWriter and LogWriter are inherited from
     47        this class. BaseWriter itself inherits from SubcontextOutputListener.
     48        It adds helper functions to configure the accepted levels and contexts.
     49
     50        The levels are not fully configurable, only the "max" form is allowed
     51        (which means that it's only possible to define a maximum level, not
     52        the full mask).
     53
     54        Contexts are defined by a vector of strings, each context is defined
     55        by it's name. Sub-contexts have the form \a "main-name::sub-name", i.e.
     56        their name is concatenated with :: in between.
     57
     58        Each instance of BaseWriter needs a name to generate distinguishable
     59        config values.
     60
     61        Received output messages are split into lines and sent line by line to
     62        the virtual printLine() function. Each line has a prepended prefix
     63        which describes the level and context of the output.
     64    */
    3765    class _UtilExport BaseWriter : public SubcontextOutputListener
    3866    {
    … …  
    4472            void setAdditionalContextsLevelMax(OutputLevel max);
    4573
     74            /// @brief Returns the name of this instance.
    4675            const std::string& getName() const
    4776                { return this->name_; }
    4877
     78            /// Config value, used to define the maximum output level (independent of contexts)
    4979            int configurableMaxLevel_;
     80            /// @brief Returns the name of the config value which defines the maximum output level (independent of contexts).
    5081            inline std::string getConfigurableMaxLevelName() const
    5182                { return this->name_ + "Level"; }
    5283
     84            /// Config value, used to define the maximum output level of additional context
    5385            int configurableAdditionalContextsMaxLevel_;
     86            /// @brief Returns the name of the config value which defines the maximum output level of additional context.
    5487            inline std::string getConfigurableAdditionalContextsMaxLevelName() const
    5588                { return this->name_ + "AdditionalContextsLevel"; }
    5689
     90            /// Config vector, used to define the additional contexts (and sub-contexts)
    5791            std::vector<std::string> configurableAdditionalContexts_;
     92            /// @brief Returns the name of the config vector which defines the additional contexts (and sub-contexts)
    5893            inline std::string getConfigurableAdditionalContextsName() const
    5994                { return this->name_ + "AdditionalContexts"; }
    … …  
    6398            void changedConfigurableAdditionalContexts();
    6499
     100            /// Returns the (static) name of the section wherein the config-values are defined.
    65101            static inline std::string getConfigurableSectionName()
    66102                { return "Output"; }
    … …  
    70106
    71107        private:
    72             virtual void printLine(const std::string& line, OutputLevel level) = 0;
     108            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.
    73109
    74             void setLevelRange(OutputLevel min, OutputLevel max);
    75             void setLevelMask(OutputLevel mask);
     110            void setLevelRange(OutputLevel min, OutputLevel max);                   ///< Inherited function, overwritten as private because it is not supported by the config-value
     111            void setLevelMask(OutputLevel mask);                                    ///< Inherited function, overwritten as private because it is not supported by the config-value
    76112
    77             void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max);
    78             void setAdditionalContextsLevelMask(OutputLevel mask);
     113            void setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max); ///< Inherited function, overwritten as private because it is not supported by the config-value
     114            void setAdditionalContextsLevelMask(OutputLevel mask);                  ///< Inherited function, overwritten as private because it is not supported by the config-value
    79115
    80             std::string name_;
     116            std::string name_; ///< The name of this instance, used to generate unique config-values
    81117    };
    82118}

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

    r8848 r8853  
    5858    share the context mask of their main-context. This allows contexts with
    5959    more descriptive names (e.g. input::keyboard) and they can be filtered
    60     individually by derivatives of orxonox::BaseWriter.
     60    individually by derivatives of orxonox::SubcontextOutputListener.
    6161*/
    6262#define REGISTER_OUTPUT_SUBCONTEXT(name, subname) \
    … …  
    160160                REGISTER_OUTPUT_SUBCONTEXT(misc, script);
    161161            }
    162 
    163162        }
    164163    }

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

    r8850 r8853  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the SubcontextOutputListener interface.
     32*/
     33
    2934#include "SubcontextOutputListener.h"
    3035
    3136namespace orxonox
    3237{
     38    /**
     39        @brief Constructor, initializes the context masks.
     40    */
    3341    SubcontextOutputListener::SubcontextOutputListener(bool bRegister) : OutputListener(bRegister)
    3442    {
    … …  
    3745    }
    3846
     47    /**
     48        @brief Destructor.
     49    */
    3950    SubcontextOutputListener::~SubcontextOutputListener()
    4051    {
    4152    }
    4253
     54    /**
     55        @brief Overwritten implementation of the function defined by OutputListener.
     56
     57        Contexts defined with this function are accepted independent of the
     58        sub-context. The "final" mask of additional contexts is defined by the
     59        combination of this mask and the masks of all accepted sub-contexts.
     60    */
    4361    void SubcontextOutputListener::setAdditionalContextsMask(OutputContextMask mask)
    4462    {
    … …  
    4866    }
    4967
     68    /**
     69        @brief Defines the set of accepted sub-contexts.
     70
     71        The masks of sub-contexts in this set are added to the mask of
     72        additional contexts, but output is only accepted if the exact
     73        sub-context exists in this set.
     74    */
    5075    void SubcontextOutputListener::setAdditionalSubcontexts(const std::set<const OutputContextContainer*>& subcontexts)
    5176    {
    … …  
    5378        this->subcontexts_.clear();
    5479
     80        // compose the mask of subcontexts and build the set of sub-context-IDs
    5581        for (std::set<const OutputContextContainer*>::const_iterator it = subcontexts.begin(); it != subcontexts.end(); ++it)
    5682        {
    … …  
    6389
    6490    /**
    65         @brief Returns true if this listener accepts output of the given level and context, based on the levels, contexts masks, and sub-contexts.
     91        @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.
    6692    */
    6793    bool SubcontextOutputListener::acceptsOutput(OutputLevel level, const OutputContextContainer& context) const

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

    r8850 r8853  
    4444namespace orxonox
    4545{
     46    /**
     47        @brief This class extends the basic OutputListener interface and adds the ability to filter sub-contexts.
     48
     49        Defining additional contexts with setAdditionalContextsMask() enables
     50        all sub-contexts of these additional contexts. To accept only some
     51        particular sub-contexts, setAdditionalSubcontexts() has to be used.
     52        Note that this requires a set, since a mask is not possible with
     53        sub-contexts.
     54
     55        The "final" context mask which will be seen by OutputManager is the
     56        combination of all regular contexts plus the masks of all sub-contexts.
     57
     58        @remark
     59        It would have been possible to implement filtering of sub-contexts
     60        directly in OutputListener and even to make OutputManager aware of
     61        sub-contexts. This would reduce the amount of unnecessarily generated
     62        output, but also increase the complexity of the checks whether some
     63        output is needed.
     64        On the other hand, filtering of sub-contexts makes the whole concept
     65        more complicated, as it adds another mask and a set. So to keep it
     66        clean and simple I figured it's best to put sub-context filtering into
     67        a seaparate class.
     68    */
    4669    class _UtilExport SubcontextOutputListener : public OutputListener
    4770    {
    … …  
    5679
    5780        private:
    58             OutputContextMask subcontextsCheckMask_;
    59             OutputContextMask subcontextsNoCheckMask_;
    60             std::set<OutputContextSubID> subcontexts_;
     81            OutputContextMask subcontextsCheckMask_;    ///< All contexts defined by this mask need to be checked whether they are accepted by the set of sub-contexts
     82            OutputContextMask subcontextsNoCheckMask_;  ///< All contexts defined by this mask don't need to be checked since we accept all sub-contexts
     83            std::set<OutputContextSubID> subcontexts_;  ///< The set of accepted sub-contexts
    6184    };
    6285}
Note: See TracChangeset for help on using the changeset viewer.