--- a/src/core/model/log.cc Fri Dec 19 13:28:03 2014 -0800
+++ b/src/core/model/log.cc Fri Dec 19 14:20:27 2014 -0800
@@ -34,30 +34,50 @@
#include <cstdlib>
#endif
+/**
+ * \file
+ * \ingroup logging
+ * Debug message logging implementation.
+ */
+
+
namespace ns3 {
+/**
+ * \ingroup logging
+ * The LogTimePrinter.
+ */
static LogTimePrinter g_logTimePrinter = 0;
+/**
+ * \ingroup logging
+ * The LogNodePrinter.
+ */
static LogNodePrinter g_logNodePrinter = 0;
-typedef LogComponent::ComponentList ComponentList;
-typedef ComponentList::iterator ComponentListI;
-
-static class PrintList
+/**
+ * \ingroup logging
+ * Handler for \c print-list token in NS_LOG
+ * to print the list of log components.
+ */
+class PrintList
{
public:
- PrintList ();
-} g_printList;
+ PrintList (); //<! Constructor, prints the list and exits.
+};
+/** Invoke handler for \c print-list in NS_LOG environment variable. */
+static PrintList g_printList;
+
+
/* static */
LogComponent::ComponentList *
LogComponent::GetComponentList (void)
{
- static ComponentList components;
+ static LogComponent::ComponentList components;
return &components;
}
-
PrintList::PrintList ()
{
#ifdef HAVE_GETENV
@@ -92,8 +112,8 @@
{
EnvVarCheck ();
- ComponentList *components = GetComponentList ();
- for (ComponentListI i = components->begin ();
+ LogComponent::ComponentList *components = GetComponentList ();
+ for (LogComponent::ComponentList::const_iterator i = components->begin ();
i != components->end ();
i++)
{
@@ -325,8 +345,8 @@
void
LogComponentEnable (char const *name, enum LogLevel level)
{
- ComponentList *components = LogComponent::GetComponentList ();
- ComponentListI i;
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ LogComponent::ComponentList::const_iterator i;
for (i = components->begin ();
i != components->end ();
i++)
@@ -349,8 +369,8 @@
void
LogComponentEnableAll (enum LogLevel level)
{
- ComponentList *components = LogComponent::GetComponentList ();
- for (ComponentListI i = components->begin ();
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ for (LogComponent::ComponentList::const_iterator i = components->begin ();
i != components->end ();
i++)
{
@@ -361,8 +381,8 @@
void
LogComponentDisable (char const *name, enum LogLevel level)
{
- ComponentList *components = LogComponent::GetComponentList ();
- for (ComponentListI i = components->begin ();
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ for (LogComponent::ComponentList::const_iterator i = components->begin ();
i != components->end ();
i++)
{
@@ -377,8 +397,8 @@
void
LogComponentDisableAll (enum LogLevel level)
{
- ComponentList *components = LogComponent::GetComponentList ();
- for (ComponentListI i = components->begin ();
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ for (LogComponent::ComponentList::const_iterator i = components->begin ();
i != components->end ();
i++)
{
@@ -389,8 +409,8 @@
void
LogComponentPrintList (void)
{
- ComponentList *components = LogComponent::GetComponentList ();
- for (ComponentListI i = components->begin ();
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ for (LogComponent::ComponentList::const_iterator i = components->begin ();
i != components->end ();
i++)
{
@@ -458,11 +478,17 @@
}
}
+/**
+ * Check if a log component exists.
+ *
+ * \param componentName The putative log component name.
+ * \returns \c true if \c componentName exists.
+ */
static bool ComponentExists(std::string componentName)
{
char const*name=componentName.c_str();
- ComponentList *components = LogComponent::GetComponentList ();
- ComponentListI i;
+ LogComponent::ComponentList *components = LogComponent::GetComponentList ();
+ LogComponent::ComponentList::const_iterator i;
for (i = components->begin ();
i != components->end ();
i++)
@@ -477,6 +503,9 @@
return false;
}
+/**
+ * Parse the \c NS_LOG environment variable.
+ */
static void CheckEnvironmentVariables (void)
{
#ifdef HAVE_GETENV
--- a/src/core/model/log.h Fri Dec 19 13:28:03 2014 -0800
+++ b/src/core/model/log.h Fri Dec 19 14:20:27 2014 -0800
@@ -29,7 +29,11 @@
#include "log-macros-enabled.h"
#include "log-macros-disabled.h"
-namespace ns3 {
+/**
+ * \file
+ * \ingroup logging
+ * Debug message logging
+ */
/**
* \ingroup debugging
@@ -38,124 +42,130 @@
* \brief Logging functions and macros
*
* LOG functionality: macros which allow developers to
- * send information to the std::clog output stream. All logging messages
- * are disabled by default. To enable selected logging
+ * send information to the \c std::clog output stream.
+ *
+ * All logging messages are disabled by default. To enable selected logging
* messages, use the ns3::LogComponentEnable
* function or use the NS_LOG environment variable
*
* Use the environment variable NS_LOG to define a ':'-separated list of
- * logging components to enable. For example (using bash syntax),
- * NS_LOG="OlsrAgent" would enable one component at all log levels.
- * NS_LOG="OlsrAgent:Ipv4L3Protocol" would enable two components,
- * at all log levels, etc.
- * NS_LOG="*" will enable all available log components at all levels.
+ * logging components to enable. For example (using bash syntax),
+ * \code
+ * $ NS_LOG="OlsrAgent" ./waf --run ...
+ * \endcode
+ * would enable one component at all log levels.
+ * \code
+ * $NS_LOG="OlsrAgent:Ipv4L3Protocol" ./waf --run ...
+ * \endcode
+ * would enable two components, at all log levels, etc.
+ * \c NS_LOG="*" will enable all available log components at all levels.
*
* To control more selectively the log levels for each component, use
- * this syntax: NS_LOG='Component1=func|warn:Component2=error|debug'
- * This example would enable the 'func', and 'warn' log
- * levels for 'Component1' and the 'error' and 'debug' log levels
- * for 'Component2'. The wildcard can be used here as well. For example
- * NS_LOG='*=level_all|prefix' would enable all log levels and prefix all
+ * this syntax:
+ * \code
+ * $ NS_LOG='Component1=func|warn:Component2=error|debug'
+ * \endcode
+ * This example would enable the \c func, and \c warn log
+ * levels for 'Component1' and the \c error and \c debug log levels
+ * for 'Component2'. The wildcard '*' can be used here as well. For example
+ * \c NS_LOG='*=level_all|prefix' would enable all log levels and prefix all
* prints with the component and function names.
*
* A note on NS_LOG_FUNCTION() and NS_LOG_FUNCTION_NOARGS():
- * generally, use of (at least) NS_LOG_FUNCTION(this) is preferred.
- * Use NS_LOG_FUNCTION_NOARGS() only in static functions.
+ * generally, use of (at least) NS_LOG_FUNCTION(this) is preferred,
+ * with the any function parameters added:
+ * \code
+ * NS_LOG_FUNCTION (this << arg1 << args);
+ * \endcode
+ * Use NS_LOG_FUNCTION_NOARGS() only in static functions with no arguments.
*/
+/** @{ */
+
+
+namespace ns3 {
/**
- * \ingroup logging
- *
* Logging severity classes and levels.
*/
enum LogLevel {
- LOG_NONE = 0x00000000, //!< no logging
+ LOG_NONE = 0x00000000, //!< No logging.
- LOG_ERROR = 0x00000001, //!< serious error messages only
- LOG_LEVEL_ERROR = 0x00000001,
+ LOG_ERROR = 0x00000001, //!< Serious error messages only.
+ LOG_LEVEL_ERROR = 0x00000001, //!< LOG_ERROR and above.
- LOG_WARN = 0x00000002, //!< warning messages
- LOG_LEVEL_WARN = 0x00000003,
+ LOG_WARN = 0x00000002, //!< Warning messages.
+ LOG_LEVEL_WARN = 0x00000003, //!< LOG_WARN and above.
- LOG_DEBUG = 0x00000004, //!< rare ad-hoc debug messages
- LOG_LEVEL_DEBUG = 0x00000007,
+ LOG_DEBUG = 0x00000004, //!< Rare ad-hoc debug messages.
+ LOG_LEVEL_DEBUG = 0x00000007, //!< LOG_DEBUG and above.
- LOG_INFO = 0x00000008, //!< informational messages (e.g., banners)
- LOG_LEVEL_INFO = 0x0000000f,
+ LOG_INFO = 0x00000008, //!< Informational messages (e.g., banners).
+ LOG_LEVEL_INFO = 0x0000000f, //!< LOG_INFO and above.
- LOG_FUNCTION = 0x00000010, //!< function tracing
- LOG_LEVEL_FUNCTION = 0x0000001f,
+ LOG_FUNCTION = 0x00000010, //!< Function tracing.
+ LOG_LEVEL_FUNCTION = 0x0000001f, //!< LOG_FUNCTION and above.
- LOG_LOGIC = 0x00000020, //!< control flow tracing within functions
- LOG_LEVEL_LOGIC = 0x0000003f,
+ LOG_LOGIC = 0x00000020, //!< Control flow tracing within functions.
+ LOG_LEVEL_LOGIC = 0x0000003f, //!< LOG_LOGIC and above.
- LOG_ALL = 0x0fffffff, //!< print everything
- LOG_LEVEL_ALL = LOG_ALL,
+ LOG_ALL = 0x0fffffff, //!< Print everything.
+ LOG_LEVEL_ALL = LOG_ALL, //!< Print everything.
- LOG_PREFIX_FUNC = 0x80000000, //!< prefix all trace prints with function
- LOG_PREFIX_TIME = 0x40000000, //!< prefix all trace prints with simulation time
- LOG_PREFIX_NODE = 0x20000000, //!< prefix all trace prints with simulation node
- LOG_PREFIX_LEVEL = 0x10000000, //!< prefix all trace prints with log level (severity)
- LOG_PREFIX_ALL = 0xf0000000 //!< all prefixes
+ LOG_PREFIX_FUNC = 0x80000000, //!< Prefix all trace prints with function.
+ LOG_PREFIX_TIME = 0x40000000, //!< Prefix all trace prints with simulation time.
+ LOG_PREFIX_NODE = 0x20000000, //!< Prefix all trace prints with simulation node.
+ LOG_PREFIX_LEVEL = 0x10000000, //!< Prefix all trace prints with log level (severity).
+ LOG_PREFIX_ALL = 0xf0000000 //!< All prefixes.
};
/**
- * \ingroup logging
- *
* Enable the logging output associated with that log component.
*
* The logging output can be later disabled with a call
* to ns3::LogComponentDisable.
*
* Same as running your program with the NS_LOG environment
- * variable set as NS_LOG='name=level'
+ * variable set as NS_LOG='name=level'.
*
- * \param name a log component name
- * \param level a logging level
+ * \param name The log component name.
+ * \param level The logging level.
*/
void LogComponentEnable (char const *name, enum LogLevel level);
/**
- * \ingroup logging
- *
* Enable the logging output for all registered log components.
*
* Same as running your program with the NS_LOG environment
* variable set as NS_LOG='*=level'
*
- * \param level a logging level
+ * \param level The logging level.
*/
void LogComponentEnableAll (enum LogLevel level);
/**
- * \ingroup logging
- *
* Disable the logging output associated with that log component.
*
* The logging output can be later re-enabled with a call
- * to ns3::LogComponentEnable.
+ * to LogComponentEnable.
*
- * \param name a log component name
- * \param level a logging level
+ * \param name The log component name.
+ * \param level The logging level.
*/
void LogComponentDisable (char const *name, enum LogLevel level);
/**
- * \ingroup logging
- *
* Disable all logging for all components.
*
- * \param level a logging level
+ * \param level The logging level.
*/
void LogComponentDisableAll (enum LogLevel level);
} // namespace ns3
+
/**
- * \ingroup logging
- *
* Define a Log component with a specific name.
*
* This macro should be used at the top of every file in which you want
@@ -174,82 +184,70 @@
* outside of namespace ns3, and after the inclusion of
* NS_LOG_COMPONENT_DEFINE, such as follows:
* \code
- * namespace ns3 {
- * NS_LOG_COMPONENT_DEFINE ("...");
+ * namespace ns3 {
+ * NS_LOG_COMPONENT_DEFINE ("...");
*
- * \\ definitions within the ns3 namespace
+ * // Definitions within the ns3 namespace
*
- * } // namespace ns3
+ * } // namespace ns3
*
- * using ns3::g_log;
+ * using ns3::g_log;
*
- * // further definitions outside of the ns3 namespace
+ * // Further definitions outside of the ns3 namespace
*\endcode
*
- * \param name a string
+ * \param name The log component name.
*/
#define NS_LOG_COMPONENT_DEFINE(name) \
static ns3::LogComponent g_log = ns3::LogComponent (name, __FILE__)
/**
- * \ingroup logging
- *
* Define a logging component with a mask.
*
* See LogComponent().
*
- * \param name a string
- * \param mask the default mask
+ * \param name The log component name.
+ * \param mask The default mask.
*/
#define NS_LOG_COMPONENT_DEFINE_MASK(name, mask) \
static ns3::LogComponent g_log = ns3::LogComponent (name, __FILE__, mask)
/**
- * \ingroup logging
- *
* Use \ref NS_LOG to output a message of level LOG_ERROR.
*
- * \param msg the message to log
+ * \param msg The message to log.
*/
#define NS_LOG_ERROR(msg) \
NS_LOG (ns3::LOG_ERROR, msg)
/**
- * \ingroup logging
- *
* Use \ref NS_LOG to output a message of level LOG_WARN.
*
- * \param msg the message to log
+ * \param msg The message to log.
*/
#define NS_LOG_WARN(msg) \
NS_LOG (ns3::LOG_WARN, msg)
/**
- * \ingroup logging
- *
* Use \ref NS_LOG to output a message of level LOG_DEBUG.
*
- * \param msg the message to log
+ * \param msg The message to log.
*/
#define NS_LOG_DEBUG(msg) \
NS_LOG (ns3::LOG_DEBUG, msg)
/**
- * \ingroup logging
- *
* Use \ref NS_LOG to output a message of level LOG_INFO.
*
- * \param msg the message to log
+ * \param msg The message to log.
*/
#define NS_LOG_INFO(msg) \
NS_LOG (ns3::LOG_INFO, msg)
/**
- * \ingroup logging
- *
* Use \ref NS_LOG to output a message of level LOG_LOGIC
*
- * \param msg the message to log
+ * \param msg The message to log.
*/
#define NS_LOG_LOGIC(msg) \
NS_LOG (ns3::LOG_LOGIC, msg)
@@ -258,36 +256,65 @@
namespace ns3 {
/**
- * \ingroup logging
- *
* Print the list of logging messages available.
* Same as running your program with the NS_LOG environment
* variable set as NS_LOG=print-list
*/
void LogComponentPrintList (void);
+/**
+ * Function signature for prepending the simulation time
+ * to a log message.
+ *
+ * \param os The output stream to print on.
+ */
typedef void (*LogTimePrinter)(std::ostream &os);
+/**
+ * Function signature for prepending the node id
+ * to a log message.
+ *
+ * \param os The output stream to print on.
+ */
typedef void (*LogNodePrinter)(std::ostream &os);
-void LogSetTimePrinter (LogTimePrinter);
+/**
+ * Set the LogTimePrinter function to be used
+ * to prepend log messages with the simulation time.
+ *
+ * \param lp The LogTimePrinter function.
+ */
+void LogSetTimePrinter (LogTimePrinter lp);
+/**
+ * Get the LogTimePrinter function currently in use.
+ * \returns The LogTimePrinter function.
+ */
LogTimePrinter LogGetTimePrinter (void);
-void LogSetNodePrinter (LogNodePrinter);
+/**
+ * Set the LogNodePrinter function to be used
+ * to prepend log messages with the node id.
+ *
+ * \param np The LogNodePrinter function.
+ */
+void LogSetNodePrinter (LogNodePrinter np);
+/**
+ * Get the LogNodePrinter function currently in use.
+ * \returns The LogNodePrinter function.
+ */
LogNodePrinter LogGetNodePrinter (void);
/**
- * \ingroup logging
- *
* A single log component configuration.
*/
class LogComponent
{
public:
/**
- * Constructor
+ * Constructor.
*
- * \param [in] name the user-visible name for this component.
+ * \param [in] name The user-visible name for this component.
+ * \param [in] file The source code file which defined this LogComponent.
* \param [in] mask LogLevels blocked for this LogComponent. Blocking
* a log level helps prevent recursion by logging in
* functions which help implement the logging facility.
@@ -296,51 +323,52 @@
const std::string & file,
const enum LogLevel mask = LOG_NONE);
/**
- * Check if this LogComponent is enabled for \pname{level}
+ * Check if this LogComponent is enabled for \c level
*
- * \param [in] level the level to check for.
- * \return true if \pname{level} is enabled.
+ * \param [in] level The level to check for.
+ * \return \c true if we are enabled at \c level.
*/
bool IsEnabled (const enum LogLevel level) const;
/**
* Check if all levels are disabled.
*
- * \return true if all levels are disabled.
+ * \return \c true if all levels are disabled.
*/
bool IsNoneEnabled (void) const;
/**
- * Enable this LogComponent at \pname{level}
+ * Enable this LogComponent at \c level
*
- * \param [in] level the LogLevel to enable.
+ * \param [in] level The LogLevel to enable.
*/
void Enable (const enum LogLevel level);
/**
- * Disable logging at \pname{level} for this LogComponent.
+ * Disable logging at \c level for this LogComponent.
*
- * \param [in] level the LogLevel to disable.
+ * \param [in] level The LogLevel to disable.
*/
void Disable (const enum LogLevel level);
/**
* Get the name of this LogComponent.
*
- * \return the name of this LogComponent.
+ * \return The name of this LogComponent.
*/
char const *Name (void) const;
/**
* Get the compilation unit defining this LogComponent.
+ * \returns The file name.
*/
std::string File (void) const;
/**
* Get the string label for the given LogLevel.
*
- * \param [in] level the LogLevel to get the label for.
- * \return the string label for \pname{level}
+ * \param [in] level The LogLevel to get the label for.
+ * \return The string label for \c level.
*/
static std::string GetLevelLabel(const enum LogLevel level);
/**
* Prevent the enabling of a specific LogLevel.
*
- * \param level the LogLevel to block
+ * \param level The LogLevel to block.
*/
void SetMask (const enum LogLevel level);
@@ -374,16 +402,15 @@
*/
void EnvVarCheck (void);
- int32_t m_levels; //!< Enabled LogLevels
- int32_t m_mask; //!< Blocked LogLevels
- std::string m_name; //!< LogComponent name
- std::string m_file; //!< File defining this LogComponent
+ int32_t m_levels; //!< Enabled LogLevels.
+ int32_t m_mask; //!< Blocked LogLevels.
+ std::string m_name; //!< LogComponent name.
+ std::string m_file; //!< File defining this LogComponent.
}; // class LogComponent
+
/**
- * \ingroup logging
- *
* Insert `, ` when streaming function arguments.
*/
class ParameterLogger
@@ -400,9 +427,10 @@
/**
* Write a function parameter on the output stream,
- * separating paramters after the first by `,` strings.
+ * separating parameters after the first by `,` strings.
*
- * \param [in] param the function parameter
+ * \param [in] param The function parameter.
+ * \return This ParameterLogger, so it's chainable.
*/
template<typename T>
ParameterLogger& operator<< (T param)
@@ -422,5 +450,6 @@
} // namespace ns3
+/**@}*/ // \ingroup logging
#endif /* NS3_LOG_H */