[Orxonox-commit 4182] r8853 - in code/branches/output/src/libraries/util: . output
landauf at orxonox.net
landauf at orxonox.net
Sun Aug 21 23:18:21 CEST 2011
Author: landauf
Date: 2011-08-21 23:18:20 +0200 (Sun, 21 Aug 2011)
New Revision: 8853
Added:
code/branches/output/src/libraries/util/output/CMakeLists.txt
Modified:
code/branches/output/src/libraries/util/CMakeLists.txt
code/branches/output/src/libraries/util/Output.h
code/branches/output/src/libraries/util/output/BaseWriter.cc
code/branches/output/src/libraries/util/output/BaseWriter.h
code/branches/output/src/libraries/util/output/OutputDefinitions.h
code/branches/output/src/libraries/util/output/SubcontextOutputListener.cc
code/branches/output/src/libraries/util/output/SubcontextOutputListener.h
Log:
documented the remaining code of the output system
created a build unit for the output system
Modified: code/branches/output/src/libraries/util/CMakeLists.txt
===================================================================
--- code/branches/output/src/libraries/util/CMakeLists.txt 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/CMakeLists.txt 2011-08-21 21:18:20 UTC (rev 8853)
@@ -38,16 +38,10 @@
Math.cc
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
FIND_HEADER_FILES
LINK_LIBRARIES
Modified: code/branches/output/src/libraries/util/Output.h
===================================================================
--- code/branches/output/src/libraries/util/Output.h 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/Output.h 2011-08-21 21:18:20 UTC (rev 8853)
@@ -44,9 +44,10 @@
Levels and contexts are defined in OutputDefinitions.h
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
A message sent to the output system MUST end with "endl" or the message
Modified: code/branches/output/src/libraries/util/output/BaseWriter.cc
===================================================================
--- code/branches/output/src/libraries/util/output/BaseWriter.cc 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/output/BaseWriter.cc 2011-08-21 21:18:20 UTC (rev 8853)
@@ -26,12 +26,20 @@
*
*/
+/**
+ @file
+ @brief Implementation of the BaseWriter class.
+*/
+
#include "BaseWriter.h"
#include "OutputManager.h"
namespace orxonox
{
+ /**
+ @brief Constructor: Initializes the config-values.
+ */
BaseWriter::BaseWriter(const std::string& name, bool bRegister) : SubcontextOutputListener(bRegister)
{
this->name_ = name;
@@ -45,10 +53,16 @@
this->changedConfigurableAdditionalContexts();
}
+ /**
+ @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)
{
const std::string& prefix = OutputManager::getInstance().getDefaultPrefix(level, context);
@@ -58,37 +72,54 @@
this->printLine((i == 0 ? prefix : blanks) + lines[i], level);
}
+ /**
+ @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
+ */
void BaseWriter::setLevelMax(OutputLevel max)
{
this->configurableMaxLevel_ = max;
this->changedConfigurableLevel();
}
+ /**
+ @brief Overwritten implementation of the function inherited from OutputListener, sets also the corresponding config-value.
+ */
void BaseWriter::setAdditionalContextsLevelMax(OutputLevel max)
{
this->configurableAdditionalContextsMaxLevel_ = max;
this->changedConfigurableAdditionalContextsLevel();
}
+ /**
+ @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
+ */
void BaseWriter::changedConfigurableLevel()
{
OutputListener::setLevelMax(static_cast<OutputLevel>(this->configurableMaxLevel_));
}
+ /**
+ @brief Called if the config value has changed, updates the corresponding mask in OutputListener.
+ */
void BaseWriter::changedConfigurableAdditionalContextsLevel()
{
OutputListener::setAdditionalContextsLevelMax(static_cast<OutputLevel>(this->configurableAdditionalContextsMaxLevel_));
}
+ /**
+ @brief Called if the config-vector of accepted contexts has changed, updates the masks in SubcontextOutputListener.
+ */
void BaseWriter::changedConfigurableAdditionalContexts()
{
OutputContextMask main_contexts = context::none;
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;
@@ -99,14 +130,17 @@
subname = full_name.substr(pos + 2);
}
+ // 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;
else
sub_contexts.insert(&context);
}
+ // pass main-contexts and sub-contexts to SubcontextOutputListener
this->setAdditionalContextsMask(main_contexts);
this->setAdditionalSubcontexts(sub_contexts);
}
Modified: code/branches/output/src/libraries/util/output/BaseWriter.h
===================================================================
--- code/branches/output/src/libraries/util/output/BaseWriter.h 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/output/BaseWriter.h 2011-08-21 21:18:20 UTC (rev 8853)
@@ -26,6 +26,12 @@
*
*/
+/**
+ @file
+ @ingroup Output
+ @brief Declaration of the BaseWriter class, the base of all output writers.
+*/
+
#ifndef _BaseWriter_H__
#define _BaseWriter_H__
@@ -34,6 +40,28 @@
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
{
public:
@@ -43,18 +71,25 @@
void setLevelMax(OutputLevel max);
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"; }
@@ -62,6 +97,7 @@
void changedConfigurableAdditionalContextsLevel();
void changedConfigurableAdditionalContexts();
+ /// Returns the (static) name of the section wherein the config-values are defined.
static inline std::string getConfigurableSectionName()
{ return "Output"; }
@@ -69,15 +105,15 @@
virtual void output(OutputLevel level, const OutputContextContainer& context, const std::vector<std::string>& lines);
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
};
}
Added: code/branches/output/src/libraries/util/output/CMakeLists.txt
===================================================================
--- code/branches/output/src/libraries/util/output/CMakeLists.txt (rev 0)
+++ code/branches/output/src/libraries/util/output/CMakeLists.txt 2011-08-21 21:18:20 UTC (rev 8853)
@@ -0,0 +1,12 @@
+ADD_SOURCE_FILES(UTIL_SRC_FILES
+BUILD_UNIT OutputBuildUnit.cc
+ OutputStream.cc
+ OutputManager.cc
+ OutputListener.cc
+ SubcontextOutputListener.cc
+ BaseWriter.cc
+ ConsoleWriter.cc
+ LogWriter.cc
+ MemoryWriter.cc
+END_BUILD_UNIT
+)
Property changes on: code/branches/output/src/libraries/util/output/CMakeLists.txt
___________________________________________________________________
Added: svn:eol-style
+ native
Modified: code/branches/output/src/libraries/util/output/OutputDefinitions.h
===================================================================
--- code/branches/output/src/libraries/util/output/OutputDefinitions.h 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/output/OutputDefinitions.h 2011-08-21 21:18:20 UTC (rev 8853)
@@ -57,7 +57,7 @@
Sub-contexts act like normal contexts, except that multiple sub-contexts
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) \
const OutputContextContainer& subname() { static const OutputContextContainer& context = registerContext(#name, #subname); return context; }
@@ -159,7 +159,6 @@
REGISTER_OUTPUT_SUBCONTEXT(misc, overlays);
REGISTER_OUTPUT_SUBCONTEXT(misc, script);
}
-
}
}
} // tolua_export
Modified: code/branches/output/src/libraries/util/output/SubcontextOutputListener.cc
===================================================================
--- code/branches/output/src/libraries/util/output/SubcontextOutputListener.cc 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/output/SubcontextOutputListener.cc 2011-08-21 21:18:20 UTC (rev 8853)
@@ -26,20 +26,38 @@
*
*/
+/**
+ @file
+ @brief Implementation of the SubcontextOutputListener interface.
+*/
+
#include "SubcontextOutputListener.h"
namespace orxonox
{
+ /**
+ @brief Constructor, initializes the context masks.
+ */
SubcontextOutputListener::SubcontextOutputListener(bool bRegister) : OutputListener(bRegister)
{
this->subcontextsCheckMask_ = context::none;
this->subcontextsNoCheckMask_ = context::none;
}
+ /**
+ @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)
{
this->subcontextsNoCheckMask_ = mask;
@@ -47,11 +65,19 @@
OutputListener::setAdditionalContextsMask(this->subcontextsCheckMask_ | this->subcontextsNoCheckMask_);
}
+ /**
+ @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)
{
this->subcontextsCheckMask_ = context::none;
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)
{
this->subcontextsCheckMask_ |= (*it)->mask;
@@ -62,7 +88,7 @@
}
/**
- @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
{
Modified: code/branches/output/src/libraries/util/output/SubcontextOutputListener.h
===================================================================
--- code/branches/output/src/libraries/util/output/SubcontextOutputListener.h 2011-08-21 21:10:54 UTC (rev 8852)
+++ code/branches/output/src/libraries/util/output/SubcontextOutputListener.h 2011-08-21 21:18:20 UTC (rev 8853)
@@ -43,6 +43,29 @@
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
{
public:
@@ -55,9 +78,9 @@
virtual bool acceptsOutput(OutputLevel level, const OutputContextContainer& context) const;
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
};
}
More information about the Orxonox-commit
mailing list