Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Aug 21, 2011, 4:04:54 PM (13 years ago)
Author:
landauf
Message:

added documentation and some comments

Location:
code/branches/output/src/libraries/util
Files:
14 edited

Legend:

Unmodified
Added
Removed
  • code/branches/output/src/libraries/util/Output.h

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @defgroup Output Output system
     31    @ingroup Util
     32*/
     33
     34/**
     35    @file
     36    @ingroup Output
     37    @brief Defines the helper function orxout() and includes all necessary headers to use the output system.
     38
     39    The output system is used to write output to the console, the logfile, and
     40    other instances of orxonox::OutputListener. Each line of output is assigned
     41    a level and a context. The level defines the type and importance of a
     42    message, e.g. if it's a fatal error or just some internal information.
     43    The context defines to which part of the program the output belongs.
     44    Levels and contexts are defined in OutputDefinitions.h
     45
     46    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.
     50
     51    @attention
     52    A message sent to the output system MUST end with "endl" or the message
     53    won't be flushed.
     54
     55    @code
     56    orxout() << "Debug output" << endl;
     57    orxout(user_info) << "Orxonox version 1.2.3" << endl;
     58    orxout(internal_status, context::input) << "Loading joystick" << endl;
     59    @endcode
     60*/
     61
    2962#ifndef _Output_H__
    3063#define _Output_H__
     
    3871    using std::endl;
    3972
     73    /**
     74        @brief This helper function returns a reference to a commonly used
     75        instance of OutputStream.
     76
     77        It can be used like std::cout except that it is a function. You can
     78        pass level and context of the following output as function arguments.
     79    */
    4080    inline OutputStream& orxout(OutputLevel level = level::debug_output, const OutputContextContainer& context = context::undefined())
    4181    {
     
    4585    }
    4686
     87    /**
     88        @brief Shortcut for orxout() to allow passing contexts directly as
     89        functions without using "()".
     90
     91        @code
     92        orxout(user_info, context::example) << "Hello World" << endl; // calls this function
     93        orxout(user_info, context::example()) << "Hello World" << endl; // calls the other orxout function
     94        @endcode
     95    */
    4796    inline OutputStream& orxout(OutputLevel level, OutputContextFunction context)
    4897    {
     
    53102    inline __DEPRECATED__(OutputStream& COUT(int level));
    54103
     104    /**
     105        @brief Writes output to the orxonox console. This function is deprecated, please use orxout()
     106        @note The output level argument is ignored since it's not supported anymore. See orxout() for the new output levels.
     107        @deprecated This function is deprecated. Use orxout() instead.
     108    */
    55109    inline OutputStream& COUT(int)
    56110    {
  • code/branches/output/src/libraries/util/output/ConsoleWriter.cc

    r8799 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the ConsoleWriter singleton.
     32*/
     33
    2934#include "ConsoleWriter.h"
    3035
     
    3540namespace orxonox
    3641{
     42    /**
     43        @brief Constructor, initializes the output level.
     44
     45        In debug builds, it writes output up to level::internal_warning to the
     46        console, in release builds only up to level::user_info.
     47
     48        After creation, the instance is enabled.
     49    */
    3750    ConsoleWriter::ConsoleWriter() : BaseWriter("Console")
    3851    {
     
    4558    }
    4659
     60    /**
     61        @brief Destructor.
     62    */
    4763    ConsoleWriter::~ConsoleWriter()
    4864    {
    4965    }
    5066
     67    /**
     68        @brief Returns the only existing instance of this class.
     69    */
    5170    /*static*/ ConsoleWriter& ConsoleWriter::getInstance()
    5271    {
     
    5574    }
    5675
     76    /**
     77        @brief Inherited function from BaseWriter, writes output to the console using std::cout.
     78    */
    5779    void ConsoleWriter::printLine(const std::string& line, OutputLevel)
    5880    {
     
    6082    }
    6183
     84    /**
     85        @brief Enables the instance by registering itself as listener at OutputManager.
     86    */
    6287    void ConsoleWriter::enable()
    6388    {
     
    6994    }
    7095
     96    /**
     97        @brief Disables the instance by unregistering itself from OutputManager.
     98    */
    7199    void ConsoleWriter::disable()
    72100    {
  • code/branches/output/src/libraries/util/output/ConsoleWriter.h

    r8795 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the ConsoleWriter singleton which is used to write output to the console.
     33*/
     34
    2935#ifndef _ConsoleWriter_H__
    3036#define _ConsoleWriter_H__
     
    3541namespace orxonox
    3642{
     43    /**
     44        @brief ConsoleWriter inherits from BaseWriter and writes output to the console.
     45
     46        This class can be seen as an equivalent to std::cout within the output
     47        system. It is implemented as a singleton for static acces.
     48    */
    3749    class _UtilExport ConsoleWriter : public BaseWriter
    3850    {
     
    5163            virtual ~ConsoleWriter();
    5264
    53             bool bEnabled_;
     65            bool bEnabled_; ///< If false, the instance will not write output to the console.
    5466    };
    5567}
  • code/branches/output/src/libraries/util/output/LogWriter.cc

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the LogWriter singleton.
     32*/
     33
    2934#include "LogWriter.h"
    3035
     
    3742namespace orxonox
    3843{
     44    /**
     45        @brief Constructor, initializes the desired output levels and the name and path of the log-file, and opens the log-file.
     46
     47        By default, LogWriter receives all output up to level::internal_info.
     48        The log-file has a default name which usually doesn't change. The path
     49        is initialized with a temporary directory, depending on the system,
     50        and can be changed later.
     51    */
    3952    LogWriter::LogWriter() : BaseWriter("Log")
    4053    {
     
    4356        this->filename_ = "orxonox.log";
    4457
    45         // Get path for a temporary file
     58        // get the path for a temporary file, depending on the system
    4659#ifdef ORXONOX_PLATFORM_WINDOWS
    4760        this->path_ = getenv("TEMP");
     
    5467    }
    5568
     69    /**
     70        @brief Destructor, closes the log-file.
     71    */
    5672    LogWriter::~LogWriter()
    5773    {
     
    5975    }
    6076
     77    /**
     78        @brief Returns the only existing instance of this class.
     79    */
    6180    /*static*/ LogWriter& LogWriter::getInstance()
    6281    {
     
    6584    }
    6685
     86    /**
     87        @brief Opens the log-file in order to write output to it.
     88    */
    6789    void LogWriter::openFile()
    6890    {
     91        // get the full file-name
    6992        std::string name = this->path_ + '/' + this->filename_;
    7093
     94        // if we open the log file in the default directory, send a message to the user so that he can find the file in the case of a crash.
    7195        if (this->bDefaultPath_)
    7296            OutputManager::getInstance().pushMessage(level::user_info, context::undefined(), "Opening log file " + name);
    7397
     98        // open the file
    7499        this->file_.open(name.c_str(), std::fstream::out);
    75100
     101        // check if it worked and print some output
    76102        if (this->file_.is_open())
    77103            this->printLine("Log file opened", level::none);
     
    80106    }
    81107
     108    /**
     109        @brief Closes the log-file.
     110    */
    82111    void LogWriter::closeFile()
    83112    {
     
    89118    }
    90119
     120    /**
     121        @brief Changes the path of the log-file. Re-writes the log-file by using MemoryWriter.
     122    */
    91123    void LogWriter::setLogPath(const std::string& path)
    92124    {
     125        // notify about the change of the log-file (because the old file will no longer be updated)
    93126        OutputManager::getInstance().pushMessage(level::internal_info, context::undefined(), "Migrating log file from " + this->path_ + "\nto " + path);
    94127
     128        // close the old file, update the path and open the new file
    95129        this->closeFile();
    96130        this->path_ = path;
     
    98132        this->openFile();
    99133
     134        // request old output from MemoryWriter
    100135        MemoryWriter::getInstance().resendOutput(this);
    101136    }
    102137
     138    /**
     139        @brief Inherited function from BaseWriter, writers output together with a timestamp to the log-file.
     140    */
    103141    void LogWriter::printLine(const std::string& line, OutputLevel)
    104142    {
     
    106144            return;
    107145
    108         // Get current time
     146        // get the current time
    109147        time_t rawtime;
    110148        struct tm* timeinfo;
     
    112150        timeinfo = localtime(&rawtime);
    113151
    114         // print timestamp and line to the log file
     152        // print timestamp and output line to the log file
    115153        this->file_ << (timeinfo->tm_hour < 10 ? "0" : "") << timeinfo->tm_hour << ':' <<
    116154                       (timeinfo->tm_min  < 10 ? "0" : "") << timeinfo->tm_min  << ':' <<
  • code/branches/output/src/libraries/util/output/LogWriter.h

    r8795 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the LogWriter singleton which writes output to a log-file.
     33*/
     34
    2935#ifndef _LogWriter_H__
    3036#define _LogWriter_H__
     
    3844namespace orxonox
    3945{
     46    /**
     47        @brief The LogWriter class inherits from BaseWriter and writes output to a log-file.
     48
     49        It is implemented as singleton because we (currently) use only one
     50        log-file. The path of the file can be changed, in which case the file
     51        is rewritten by using the output stored by MemoryWriter. This adds the
     52        possibility to change the desired output levels before changing the
     53        path in order to get the complete output with the new output levels
     54        at the new path.
     55    */
    4056    class _UtilExport LogWriter : public BaseWriter
    4157    {
     
    5672            void closeFile();
    5773
    58             std::string filename_;
    59             std::string path_;
    60             bool bDefaultPath_;
     74            std::string filename_;  ///< The name of the log-file (without directories)
     75            std::string path_;      ///< The path of the log-file (without file-name)
     76            bool bDefaultPath_;     ///< If true, the log-file resides at the default path (which is usually a temporary directory)
    6177
    62             std::ofstream file_;
     78            std::ofstream file_;    ///< The output file stream.
    6379    };
    6480}
  • code/branches/output/src/libraries/util/output/MemoryWriter.cc

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the MemoryWriter singleton.
     32*/
     33
    2934#include "MemoryWriter.h"
    30 
    3135#include "OutputManager.h"
    3236
    3337namespace orxonox
    3438{
     39    /**
     40        @brief Constructor, initializes the level mask with all levels activated.
     41    */
    3542    MemoryWriter::MemoryWriter()
    3643    {
     
    3845    }
    3946
     47    /**
     48        @brief Destructor.
     49    */
    4050    MemoryWriter::~MemoryWriter()
    4151    {
    4252    }
    4353
     54    /**
     55        @brief Returns the only existing instance of this singleton class.
     56    */
    4457    /*static*/ MemoryWriter& MemoryWriter::getInstance()
    4558    {
     
    4861    }
    4962
     63    /**
     64        @brief Implementation of the output() function inherited from OutputListener, stores the received output in memory.
     65    */
    5066    void MemoryWriter::output(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines)
    5167    {
     
    5369    }
    5470
     71    /**
     72        @brief Iterates over all stored output messages and sends them to the OutputListener.
     73    */
    5574    void MemoryWriter::resendOutput(OutputListener* listener) const
    5675    {
     
    6281    }
    6382
     83    /**
     84        @brief Unregisters the instance from OutputManager, hence it will not receive any further output.
     85    */
    6486    void MemoryWriter::disable()
    6587    {
  • code/branches/output/src/libraries/util/output/MemoryWriter.h

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the MemoryWriter singleton.
     33*/
     34
    2935#ifndef _MemoryWriter_H__
    3036#define _MemoryWriter_H__
     
    3541namespace orxonox
    3642{
     43    /**
     44        @brief MemoryWriter is a singleton which is derived from OutputListener and writes all output to a list.
     45
     46        This list can be used to re-send old output to other instances of
     47        OutputListener, e.g. if they were newly created or to re-write the
     48        log-file.
     49
     50        Since MemoryWriter receives output of all levels, this means also that
     51        all possible output needs to be generated as long as MemoryWriter stays
     52        active. Hence disable() should be called as soon as possible.
     53    */
    3754    class _UtilExport MemoryWriter : public OutputListener
    3855    {
     56        /// @brief A helper struct which is used to store output and its properties.
    3957        struct Message
    4058        {
     59            /// @brief Constructor, assigns all values.
    4160            Message(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines)
    4261                : level(level), context(&context), lines(lines) {}
    4362
    44             OutputLevel level;
    45             const OutputContextContainer* context;
    46             std::vector<std::string> lines;
     63            OutputLevel level;                      ///< The level of the output message
     64            const OutputContextContainer* context;  ///< The context of the output message
     65            std::vector<std::string> lines;         ///< The lines of text of the output message
    4766        };
    4867
     
    6180            virtual ~MemoryWriter();
    6281
    63             std::vector<Message> messages_;
     82            std::vector<Message> messages_; ///< Stores all output messages from the creation of this instance until disable() is called.
    6483    };
    6584}
  • code/branches/output/src/libraries/util/output/OutputDefinitions.h

    r8840 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Defines output levels and output contexts.
     33*/
     34
    2935#ifndef _OutputDefinitions_H__
    3036#define _OutputDefinitions_H__
     
    3339#include <string>
    3440
     41/**
     42    @brief Defines a context function with a given name.
     43    @param name Name of the context
     44
     45    Context functions return a reference to a OutputContextContainer. Context
     46    functions (or the containers they return) can be passed to orxout() as
     47    context argument.
     48*/
    3549#define REGISTER_OUTPUT_CONTEXT(name) \
    3650    const OutputContextContainer& name() { static const OutputContextContainer& context = registerContext(#name); return context; }
    3751
     52/**
     53    @brief Defines a sub-context.
     54    @param name Name of the main-context
     55    @param subname Name of the sub-context
     56
     57    Sub-contexts act like normal contexts, except that multiple sub-contexts
     58    share the context mask of their main-context. This allows contexts with
     59    more descriptive names (e.g. input::keyboard) and they can be filtered
     60    individually by derivatives of orxonox::BaseWriter.
     61*/
    3862#define REGISTER_OUTPUT_SUBCONTEXT(name, subname) \
    3963    const OutputContextContainer& subname() { static const OutputContextContainer& context = registerContext(#name, #subname); return context; }
     
    4468    namespace level
    4569    {
     70        /**
     71            @brief Output levels define type and importance of an output message.
     72            They can be passed to the orxout() function as level argument.
     73        */
    4674        enum OutputLevel
    4775        {
    48             all              = 0xFFFF,
    49             none             = 0x0000,
     76            all              = 0xFFFF, ///< Level mask with all bits set to 1
     77            none             = 0x0000, ///< Level mask with all bits set to 0
    5078
    51             message          = 0x0001,
    52             debug_output     = 0x0002,
    53             user_error       = 0x0004,
    54             user_warning     = 0x0008,
    55             user_status      = 0x0010,
    56             user_info        = 0x0020,
    57             internal_error   = 0x0040,
    58             internal_warning = 0x0080,
    59             internal_status  = 0x0100,
    60             internal_info    = 0x0200,
    61             verbose          = 0x0400,
    62             verbose_more     = 0x0800,
    63             verbose_ultra    = 0x1000
     79            message          = 0x0001, ///< Output level, used for messages directed to the user (e.g. "Press any key to continue")
     80            debug_output     = 0x0002, ///< Output level, used for temporary debug output while writing code
     81            user_error       = 0x0004, ///< Output level, used for error messages which are important for the user
     82            user_warning     = 0x0008, ///< Output level, used for warnings which are important for the user
     83            user_status      = 0x0010, ///< Output level, used to notify the user about the program's state
     84            user_info        = 0x0020, ///< Output level, used to provide the user with additional progress information
     85            internal_error   = 0x0040, ///< Output level, used for error messages which are important for developers
     86            internal_warning = 0x0080, ///< Output level, used for warnings which are important for developers
     87            internal_status  = 0x0100, ///< Output level, used to log the program's internal state in the log file
     88            internal_info    = 0x0200, ///< Output level, used to log information about the program's progress in the log file
     89            verbose          = 0x0400, ///< Output level, usually not visible, used for unimportant debug information
     90            verbose_more     = 0x0800, ///< Output level, usually not visible, used for unimportant debug information (less important than verbose)
     91            verbose_ultra    = 0x1000  ///< Output level, usually not visible, used for unimportant debug information (even less important than verbose_more)
    6492        };
    6593    }
     
    6896    using namespace level;
    6997
    70     typedef uint64_t OutputContextMask;
    71     typedef uint16_t OutputContextSubID;
     98    typedef uint64_t OutputContextMask;  ///< Used to store the context masks. Each bit defines a context.
     99    typedef uint16_t OutputContextSubID; ///< Used to store the IDs of sub-contexts. Each number except context::no_subcontext defines a sub-context.
    72100
     101    /// @brief Stores all information about a context.
    73102    struct OutputContextContainer
    74103    {
    75         OutputContextMask mask;
    76         OutputContextSubID sub_id;
    77         std::string name;
     104        OutputContextMask mask;     ///< The mask of the context (or the mask of the main-context if this container defines a sub-context)
     105        OutputContextSubID sub_id;  ///< The id of the sub-context (or context::no_subcontext if this container doesn't define a sub-context)
     106        std::string name;           ///< The name of this context
    78107    };
    79108
    80109    typedef const OutputContextContainer& (OutputContextFunction)();
    81110
     111    /**
     112        @brief Registers a context.
     113        This is a shortcut to OutputManager::registerContext() to avoid the inclusion of its header file.
     114    */
    82115    extern _UtilExport const OutputContextContainer& registerContext(const std::string& name, const std::string& subname = "");
    83116
    84117    namespace context
    85118    {
    86         static const OutputContextMask all       = 0xFFFFFFFFFFFFFFFF;
    87         static const OutputContextMask none      = 0x0000000000000000;
     119        static const OutputContextMask all       = 0xFFFFFFFFFFFFFFFF; ///< Context mask, all bits set to 1
     120        static const OutputContextMask none      = 0x0000000000000000; ///< Context mask, all bits set to 0
    88121
    89         static const OutputContextSubID no_subcontext = 0;
     122        static const OutputContextSubID no_subcontext = 0; ///< Used as ID for contexts which are not sub-contexts
    90123
    91124        namespace
    92125        {
    93             REGISTER_OUTPUT_CONTEXT(undefined);
     126            REGISTER_OUTPUT_CONTEXT(undefined); ///< "undefined" context which is implicitly used for all output that has no explicit context
    94127
    95128            REGISTER_OUTPUT_CONTEXT(ogre);
  • code/branches/output/src/libraries/util/output/OutputListener.cc

    r8834 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the OutputListener class.
     32*/
     33
    2934#include "OutputListener.h"
    3035
     
    3338namespace orxonox
    3439{
     40    /**
     41        @brief Constructor, initializes the values and registers the instance at OutputManager if requested.
     42        @param bRegister If \c true, the instance is automatically registered at OutputManager.
     43                         Should be \c false if the constructor of the derived class generates output.
     44    */
    3545    OutputListener::OutputListener(bool bRegister)
    3646    {
     
    4353    }
    4454
     55    /**
     56        @brief Destructor, unregisters the instance from OutputManager.
     57    */
    4558    OutputListener::~OutputListener()
    4659    {
     
    4861    }
    4962
     63    /**
     64        @brief Defines the level mask in a way which accepts all output up to the level \c max.
     65    */
    5066    void OutputListener::setLevelMax(OutputLevel max)
    5167    {
     
    5369    }
    5470
     71    /**
     72        @brief Defines the level mask in a way which accepts all output between the levels \c min and \c max.
     73    */
    5574    void OutputListener::setLevelRange(OutputLevel min, OutputLevel max)
    5675    {
     
    6281    }
    6382
     83    /**
     84        @brief Defines the level mask.
     85    */
    6486    void OutputListener::setLevelMask(OutputLevel mask)
    6587    {
     
    6991    }
    7092
     93    /**
     94        @brief Defines the level mask of additional contexts in a way which accepts all output up to the level \c max.
     95    */
    7196    void OutputListener::setAdditionalContextsLevelMax(OutputLevel max)
    7297    {
     
    7499    }
    75100
     101    /**
     102        @brief Defines the level mask of additional contexts in a way which accepts all output between the levels \c min and \c max.
     103    */
    76104    void OutputListener::setAdditionalContextsLevelRange(OutputLevel min, OutputLevel max)
    77105    {
     
    83111    }
    84112
     113    /**
     114        @brief Defines the level mask of additional contexts.
     115    */
    85116    void OutputListener::setAdditionalContextsLevelMask(OutputLevel mask)
    86117    {
     
    90121    }
    91122
     123    /**
     124        @brief Defines the mask of additional contexts.
     125    */
    92126    void OutputListener::setAdditionalContextsMask(OutputContextMask mask)
    93127    {
  • code/branches/output/src/libraries/util/output/OutputListener.h

    r8834 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the OutputListener interface which receives output
     33    from orxonox::OutputManager.
     34*/
     35
    2936#ifndef _OutputListener_H__
    3037#define _OutputListener_H__
     
    3845namespace orxonox
    3946{
     47    /**
     48        @brief OutputListener is an interface which is used to receive output of a certain level and context from OutputManager.
     49    */
     50    //  See below the class declaration for a more detailed description.
    4051    class _UtilExport OutputListener
    4152    {
     
    5465            void setAdditionalContextsMask(OutputContextMask mask);
    5566
     67            /// @brief Returns the level mask.
    5668            inline OutputLevel getLevelMask() const
    5769                { return this->levelMask_; }
     70            /// @brief Returns the additional contexts mask.
     71            inline OutputContextMask getAdditionalContextsMask() const
     72                { return this->additionalContextsMask_; }
     73            /// @brief Returns the additional contexts level mask.
    5874            inline OutputLevel getAdditionalContextsLevelMask() const
    5975                { return this->additionalContextsLevelMask_; }
    60             inline OutputContextMask getAdditionalContextsMask() const
    61                 { return this->additionalContextsMask_; }
    6276
     77            /// @brief Returns true if this listener accepts output of the given level and context, based on the levels and contexts masks.
    6378            inline bool acceptsOutput(OutputLevel level, const OutputContextContainer& context) const
    6479            {
     
    6681                       ((this->additionalContextsLevelMask_ & level) && (this->additionalContextsMask_ & context.mask)); }
    6782
     83            /// @brief Called by OutputManager for each line of output, checks if this listener actually accepts this output before it calls the output() function.
    6884            inline void unfilteredOutput(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines)
    6985                { if (this->acceptsOutput(level, context)) this->output(level, context, lines); }
    7086
    7187        protected:
     88            /// @brief Pure virtual function, needs to be implemented in order to receive output.
    7289            virtual void output(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines) = 0;
    7390
    7491        private:
    75             OutputLevel       levelMask_;
    76             OutputLevel       additionalContextsLevelMask_;
    77             OutputContextMask additionalContextsMask_;
     92            OutputLevel       levelMask_;                   ///< Mask of accepted output levels, independent of contexts
     93            OutputContextMask additionalContextsMask_;      ///< Mask of accepted additional contexts
     94            OutputLevel       additionalContextsLevelMask_; ///< Mask of accepted output levels of the additional contexts
    7895    };
     96
     97    /**
     98        @class OutputListener
     99
     100        An instance of OutputListener registers itself at OutputManager and
     101        declares the desired output levels and contexts. OutputManager will
     102        then send output to it by calling the output() function.
     103
     104        OutputListener has 3 masks to define the desired output. These masks
     105        can be used in two different ways (or as a combination of both):
     106        \li 1. By defining the \a "level mask": The OutputListener will then
     107               receive all output of these levels independent of the context.
     108        \li 2. By defining the \a "additional contexts mask" and the
     109               \a "additional contexts level mask": This way the listener
     110               receives only output of a particular context and level.
     111        \li 3. By using all 3 masks which combines the output defined by the
     112               first two ways.
     113
     114        This can be illustrated as follows:
     115
     116        1. Only level mask:
     117        \li level-mask = error | warning;
     118
     119        @verbatim
     120                |   Contexts:   |
     121                | A | B | C | D |
     122        --------|---|---|---|---|
     123        debug   | - | - | - | - |
     124        --------|---|---|---|---|
     125        error   | x | x | x | x |
     126        --------|---|---|---|---|       [x] Receives output
     127        warning | x | x | x | x |       [-] Does not receive output
     128        --------|---|---|---|---|
     129        status  | - | - | - | - |
     130        --------|---|---|---|---|
     131        verbose | - | - | - | - |
     132        --------|---|---|---|---|
     133        @endverbatim
     134
     135        2. Only additional contexts:
     136        \li additional-contexts-mask = B | D;
     137        \li additional-contexts-level-mask = debug | verbose;
     138
     139        @verbatim
     140                |   Contexts:   |
     141                | A | B | C | D |
     142        --------|---|---|---|---|
     143        debug   | - | x | - | x |
     144        --------|---|---|---|---|
     145        error   | - | - | - | - |
     146        --------|---|---|---|---|       [x] Receives output
     147        warning | - | - | - | - |       [-] Does not receive output
     148        --------|---|---|---|---|
     149        status  | - | - | - | - |
     150        --------|---|---|---|---|
     151        verbose | - | x | - | x |
     152        --------|---|---|---|---|
     153        @endverbatim
     154
     155        3. Both level mask plus additional contexts:
     156        \li level-mask = error | warning;
     157        \li additional-contexts-mask = B | D;
     158        \li additional-contexts-level-mask = debug | verbose;
     159
     160        @verbatim
     161                |   Contexts:   |
     162                | A | B | C | D |
     163        --------|---|---|---|---|
     164        debug   | - | x | - | x |
     165        --------|---|---|---|---|
     166        error   | x | x | x | x |
     167        --------|---|---|---|---|       [x] Receives output
     168        warning | x | x | x | x |       [-] Does not receive output
     169        --------|---|---|---|---|
     170        status  | - | - | - | - |
     171        --------|---|---|---|---|
     172        verbose | - | x | - | x |
     173        --------|---|---|---|---|
     174        @endverbatim
     175    */
    79176}
    80177
  • code/branches/output/src/libraries/util/output/OutputManager.cc

    r8833 r8848  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of the OutputManager singleton.
     32*/
    2833
    2934#include "OutputManager.h"
     
    3742namespace orxonox
    3843{
     44    /**
     45        @brief Constructor, initializes all values.
     46    */
    3947    OutputManager::OutputManager()
    4048    {
     
    4654    }
    4755
     56    /**
     57        @brief Destructor.
     58    */
    4859    OutputManager::~OutputManager()
    4960    {
    5061    }
    5162
     63    /**
     64        @brief Returns the only existing instance of the OutputManager singleton.
     65    */
    5266    /*static*/ OutputManager& OutputManager::getInstance()
    5367    {
     
    5670    }
    5771
     72    /**
     73        @brief Returns the only existing instance of the OutputManager singleton
     74        and ensures that the most important output listeners exist.
     75
     76        You should use this function if you send output to OutputManager and want
     77        to be sure that the most important output listeners exist. Don't use it
     78        elsewhere inside the output system to avoid circular calls.
     79    */
    5880    /*static*/ OutputManager& OutputManager::getInstanceAndCreateListeners()
    5981    {
     
    6789    }
    6890
     91    /**
     92        @brief Sends an output message to all output listeners.
     93        @param level The level of the message
     94        @param context The context of the message
     95        @param message The output message (may contain '\\n')
     96
     97        This function splits the message into lines (if it contains '\\n') and
     98        sends it to the output listeners. They may ignore the message if it
     99        doesn't match their level- and context-masks.
     100    */
    69101    void OutputManager::pushMessage(OutputLevel level, const OutputContextContainer& context, const std::string& message)
    70102    {
     
    76108    }
    77109
     110    /**
     111        @brief Adds an output listener to the list of listeners.
     112    */
    78113    void OutputManager::registerListener(OutputListener* listener)
    79114    {
     
    82117    }
    83118
     119    /**
     120        @brief Removes an output listener from the list of listeners.
     121    */
    84122    void OutputManager::unregisterListener(OutputListener* listener)
    85123    {
     
    95133    }
    96134
     135    /**
     136        @brief Updates all three combined level- and context-masks.
     137    */
    97138    void OutputManager::updateMasks()
    98139    {
     
    102143    }
    103144
     145    /**
     146        @brief Updates the combined level mask. The masks of all listeners are ORed to form the combined mask.
     147    */
    104148    void OutputManager::updateCombinedLevelMask()
    105149    {
     
    110154    }
    111155
     156    /**
     157        @brief Updates the combined additional contexts level mask. The masks of all listeners are ORed to form the combined mask.
     158    */
    112159    void OutputManager::updateCombinedAdditionalContextsLevelMask()
    113160    {
     
    118165    }
    119166
     167    /**
     168        @brief Updates the combined additional contexts mask. The masks of all listeners are ORed to form the combined mask.
     169    */
    120170    void OutputManager::updateCombinedAdditionalContextsMask()
    121171    {
     
    125175    }
    126176
     177    /**
     178        @brief Registers a context (or sub-context) and returns the container which identifies the context.
     179        @param name The name of the context
     180        @param subname The name of the sub-context (or "" if it is not a sub-context)
     181
     182        If the context doesn't exist, it gets created. Otherwise the existing instance is returned.
     183    */
    127184    const OutputContextContainer& OutputManager::registerContext(const std::string& name, const std::string& subname)
    128185    {
     186        // the full name of a context is a combination of name and subname with "::" in between
    129187        std::string full_name = name;
    130188        if (subname != "")
    131189            full_name += "::" + subname;
    132190
     191        // check if the context already exists (and return it if it does)
    133192        std::map<std::string, OutputContextContainer>::iterator it_container = this->contextContainers_.find(full_name);
    134193        if (it_container != this->contextContainers_.end())
    135194            return it_container->second;
    136195
     196        // create a new context container
    137197        OutputContextContainer container;
    138198        container.name = full_name;
    139199
     200        // check if the mask of the main-context already exists
    140201        std::map<std::string, OutputContextMask>::iterator it_mask = this->contextMasks_.find(name);
    141202        if (it_mask != this->contextMasks_.end())
    142203        {
     204            // the mask exists, assign it to the container
    143205            container.mask = it_mask->second;
    144206        }
    145207        else
    146208        {
     209            // the mask doesn't exist, create it. It's a binary mask. The n-th main-context is defined by the n-th bit in the mask.
    147210            container.mask = static_cast<OutputContextMask>(0x1) << this->contextMasks_.size();
    148211            this->contextMasks_[name] = container.mask;
     
    152215        }
    153216
     217        // if the context is a sub-context, assign a unique ID.
    154218        if (subname == "")
    155219            container.sub_id = context::no_subcontext;
     
    157221            container.sub_id = ++this->subcontextCounter_; // start with 1
    158222
     223        // add the new context to the map and return it
    159224        return (this->contextContainers_[full_name] = container);
    160225    }
    161226
     227    /**
     228        @brief Static function, shortcut to OutputManager::registerContext().
     229        The function is declared in OutputDefinitions.h.
     230    */
    162231    const OutputContextContainer& registerContext(const std::string& name, const std::string& subname)
    163232    {
     
    165234    }
    166235
     236    /**
     237        @brief Returns a human readable string for each output level.
     238    */
    167239    const std::string& OutputManager::getLevelName(OutputLevel level) const
    168240    {
    169241        switch (level)
    170242        {
     243            // using static cache variables for speed
    171244            case level::none:               { static std::string name = "None"; return name; }
    172245            case level::message:            { static std::string name = "Message"; return name; }
     
    187260    }
    188261
     262    /**
     263        @brief Returns a string containing the name of the level and the context (if any) which
     264        can be prepended to an output message if it is written to the console or the log file.
     265    */
    189266    std::string OutputManager::getDefaultPrefix(OutputLevel level, const OutputContextContainer& context) const
    190267    {
     268        // "undefined" context is ignored because it's used implicitly if no explicit context is defined
    191269        static OutputContextMask undefined_mask = context::undefined().mask;
    192270
  • code/branches/output/src/libraries/util/output/OutputManager.h

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the OutputManager class which receives output from orxonox::OutputStream
     33    and distributes it to all instances of orxonox::OutputListener.
     34*/
     35
    2936#ifndef _OutputManager_H__
    3037#define _OutputManager_H__
     
    3946namespace orxonox
    4047{
     48    /**
     49        @brief OutputManager acts as the center of the output system and is implemented as a singleton.
     50
     51        All instances of OutputStream (and hence also the orxout() function)
     52        send their buffered output to OutputManager. OutputManager then
     53        distributes this output to all registered instances of OutputListener.
     54
     55        For each listener OutputManager checks if it wants to receive output
     56        with the given level and context. OutputManager itself also maintains
     57        masks that define the accepted levels and concept. They are a
     58        combination of the masks of all output listeners. See the description
     59        of OutputListener for a more conclusive description of these masks.
     60
     61        Additionally OutputManager is used to register output contexts.
     62    */
    4163    class _UtilExport OutputManager
    4264    {
     
    5577            void updateCombinedAdditionalContextsMask();
    5678
     79            /**
     80                @brief Returns true if at least one of the output listeners will accept output with the given level and context.
     81
     82                For the sake of performance, output messages with levels or
     83                contexts that are not accepted should be ignored or, even
     84                better, not generated at all.
     85            */
    5786            inline bool acceptsOutput(OutputLevel level, const OutputContextContainer& context) const
    5887            {
     
    71100            ~OutputManager();
    72101
    73             std::vector<OutputListener*> listeners_;
     102            std::vector<OutputListener*> listeners_;                            ///< List of all registered output listeners
    74103
    75             OutputLevel       combinedLevelMask_;
    76             OutputLevel       combinedAdditionalContextsLevelMask_;
    77             OutputContextMask combinedAdditionalContextsMask_;
     104            OutputLevel       combinedLevelMask_;                               ///< The combined mask of accepted levels of all listeners
     105            OutputLevel       combinedAdditionalContextsLevelMask_;             ///< The combined mask of accepted additional contexts levels of all listeners
     106            OutputContextMask combinedAdditionalContextsMask_;                  ///< The combined mask of accepted additional contexts of all listeners
    78107
    79             std::map<std::string, OutputContextMask> contextMasks_;
    80             std::map<std::string, OutputContextContainer> contextContainers_;
    81             OutputContextSubID subcontextCounter_;
     108            std::map<std::string, OutputContextMask> contextMasks_;             ///< Contains all main-contexts and their masks
     109            std::map<std::string, OutputContextContainer> contextContainers_;   ///< Contains all contexts including sub-contexts and their containers
     110            OutputContextSubID subcontextCounter_;                              ///< Counts the number of sub-contexts (and generates their IDs)
    82111    };
    83112}
  • code/branches/output/src/libraries/util/output/OutputStream.cc

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of the non-generic functions of the OutputStream class.
     32*/
     33
    2934#include "OutputStream.h"
    3035
     
    3338namespace orxonox
    3439{
     40    /**
     41        @brief Default constructor, initializes level and context with default values.
     42    */
    3543    OutputStream::OutputStream()
    3644    {
     
    3846    }
    3947
     48    /**
     49        @brief Constructor, initializes level and context with the provided values.
     50    */
    4051    OutputStream::OutputStream(OutputLevel level, const OutputContextContainer& context)
    4152    {
     
    4354    }
    4455
     56    /**
     57        @brief Sends the buffered message to OutputManager together with the stored level and context.
     58        Additionally empties the buffer.
     59    */
    4560    void OutputStream::sendMessage()
    4661    {
     
    4964    }
    5065
     66    /**
     67        @brief Defines level and context of the following output.
     68        Also sets the bAcceptsOutput_ flag according to the masks defined in OutputManager.
     69    */
    5170    void OutputStream::setOutputAttributes(OutputLevel level, const OutputContextContainer& context)
    5271    {
  • code/branches/output/src/libraries/util/output/OutputStream.h

    r8833 r8848  
    2727 */
    2828
     29/**
     30    @file
     31    @ingroup Output
     32    @brief Declaration of the OutputStream class which is used to send output to orxonox::OutputManager.
     33*/
     34
    2935#ifndef _OutputStream_H__
    3036#define _OutputStream_H__
     
    3844namespace orxonox
    3945{
     46    /**
     47        @brief This class is used to buffer output and send it to OutputManager whenever std::endl is passed to it.
     48
     49        OutputStream inherits from std::ostringstream and acts like std::cout.
     50        This means you can use the << operator to write output to the stream.
     51        This class is used by the orxout() function.
     52
     53        @attention
     54        You must end an output message with std::endl, otherwise the message
     55        won't be flushed. '\\n' only adds a new line to the message.
     56
     57        The following code samples are all equivalent:
     58        @code
     59        OutputStream stream;
     60        stream.setOutputAttributes(user_info, context::example());
     61        stream << "Hello World" << endl;
     62        @endcode
     63
     64        @code
     65        OutputStream stream(user_info, context::example());
     66        stream << "Hello World" << endl;
     67        @endcode
     68
     69        @code
     70        orxout(user_info, context::example) << "Hello World" << endl;
     71        @endcode
     72    */
    4073    class OutputStream : public std::ostringstream
    4174    {
     
    4881            void _UtilExport setOutputAttributes(OutputLevel level, const OutputContextContainer& context);
    4982
     83            /// @brief Generic << operator which adds output to the stream.
    5084            template <class T>
    5185            inline OutputStream& operator<<(const T& val) { return this->output(val); }
     86            /// @brief Sends a manipulator to the output stream.
    5287            inline OutputStream& operator<<(std::ios_base& (*manipulator)(std::ios_base&)) { return this->output(manipulator); }
     88            /// @brief Sends a manipulator to the output stream.
    5389            inline OutputStream& operator<<(std::ios&      (*manipulator)(std::ios&))      { return this->output(manipulator); }
     90            /// @brief Sends a manipulator to the output stream and flushes the message if the manipulator is std::endl.
    5491            inline OutputStream& operator<<(std::ostream&  (*manipulator)(std::ostream&))
    5592            {
     
    5794                {
    5895                    if (manipulator == static_cast<EndlType>(std::endl))
    59                         this->sendMessage();
     96                        this->sendMessage(); // send the message to OutputManager
    6097                    else
    61                         return this->output(manipulator);
     98                        return this->output(manipulator); // apply the manipulator
    6299                }
    63100                return *this;
     
    65102
    66103        private:
     104            /// @brief Generic function to add values to the output stream, using the inherited << operator from std::ostringstream.
    67105            template <class T>
    68106            inline OutputStream& output(const T& val)
     
    75113            void _UtilExport sendMessage();
    76114
    77             OutputLevel level_;
    78             const OutputContextContainer* context_;
    79             bool bAcceptsOutput_;
     115            OutputLevel level_;                     ///< The output level of the current message
     116            const OutputContextContainer* context_; ///< The output context of the current message
     117            bool bAcceptsOutput_;                   ///< After defining level and context of the following message, this flag is set according to the masks defined in OutputManager. If it is false, the OutputStream will throw away every output sent using the << operator.
    80118    };
    81119}
Note: See TracChangeset for help on using the changeset viewer.