vos/corelibs/vos/log.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001, 2002 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <tetron@interreality.org>
*/
#ifndef _LOG_HH_
#define _LOG_HH_

/** @file
    Defines Log.
    @see LOG
*/

#include <vos/corelibs/vos/vosdefs.hh>

#include <string>
#include <map>

/** @def LOG(c, l, m) log.hh vos/corelibs/vos/log.hh

    @param c (string) the logging channel, which will be created if it does not exist
    @param l (int) the logging level (0 is the highest priority, 5
    being the lowest priority.
    @param m The actual log message.  This is actually used as an
    output into a stream, so the whole C++ stream output API is available
    In other words, can use expressions like:
    @code
        LOG("foo", 3, "x = " << x << "\n");
    @endcode

    You can control log levels using the setLevel(), setDefaultLevel(), setMasterLevel(), and
    also by setting an environment variables named <code>VOS_LOG</code> and <code>VOS_MASTER_LOGLEVEL</code>.
    The LOG macro first checks the master loglevel. If (l) is greater than the master level, no logging message will be printed.
    Next, LOG checks the level for the channel. if (l) is less than or equal to the channel's level, the message is printed.

    The format of the <code>VOS_LOG</code> environment variable is <code>channel1=level1,channel2=level2,...</code>.
    Don't use any spaces.
    <code>VOS_MASTER_LOGLEVEL</code> should contain a single (positive) integer.
    Both environment variables are entirely optional.

    LOG must be a macro because of the way output streams are used (believe
    me, I tried other ways...)  Note that also, because it is a macro,
    you pay no penalty related to creating output the if string if it isn't going
    be printed; the log level is checked beforehand.
*/

#define LOG_MAXLINELENGTH 1024

#ifdef USE_STRSTREAM
#include <strstream>
#define LOG(c, l, m) {                 \
    if(l <= Log::masterLogLevel) {      \
        Log* _lg = Log::getLog(c);         \
        if(! _lg) { _lg=new Log(c); Log::addChannel(_lg); }  \
        if(_lg->getLevel() >= l) {          \
          char _y[LOG_MAXLINELENGTH];                   \
          memset(_y, 0, sizeof(_y));       \
          ostrstream _x(_y, sizeof(_y)-1); \
          _x << m;                        \
          _lg->log(l, _x.str());           \
        } \
    }                                  \
}
#else
#include <sstream>
#define LOG(c, l, m) {         \
    if(l <= Log::masterLogLevel) { \
        Log* _lg = Log::getLog(c); \
        if(! _lg) { _lg=new Log(c); Log::addChannel(_lg); }  \
        if(_lg->getLevel() >= l) {  \
          ostringstream _x;        \
          _x << m;                 \
          _lg->log(l, _x.str());    \
        }                          \
    } \
}
#endif

namespace VOS
{
/** @class Log log.hh vos/corelibs/vos/log.hh
 *
 * The logging class.  The main user interface to this class is the macro LOG(),
 * but you can set some global options using the static methods in this class,
 * and you can set properties of individual channels using this class.
 */
class VOS_API Log
{
private:
    string channelname;
    std::ostream* output;
    int loglevel;

    class StrCmp {
    public:
        inline bool operator()(const char* p, const char* q) const {
            return (strcmp(p, q) < 0);
        };
    };

    static map<const char*, Log*, StrCmp> channels;
    static std::ostream* defaultostream;
    static int defaultloglevel;
    static bool didReadEnv;
public:

    /** A level that applies to all channels. (default is 10) */
    static int masterLogLevel;

    static boost::mutex log_io_mutex;

    /** Construct a new logging channel.  Usually you
        don't need to call this, as it will be created automatically
        when a new channel is refered to.
        @param channel the channel name that will select this log object
        @param outputstream the output stream this log will write to
        @internal
    */
    Log(const string& channel, std::ostream* outputstream);

    /** Construct a new logging channel.  Usually you
        don't need to call this, as it will be created automatically
        when a new channel is refered to.
        @param channel the channel name that will select this log object
        @internal
    */
    Log(const string& channel);

    /** Write a line to the logfile.  You probably want to be
        using LOG(), however.
        @param level the level to log at.  If the logging channel
        level is lower than this level, the log message will be suppressed
        @param message the message string to print
        @internal
    */
    void log(int level, const string& message);

    /** Set the log level for this channel. Log levels for channels can also be set with an environment variable VOS_LOG, which takes the format channel:level,channel:level, etc. -- channel is the name of a log channel, and level is the integer level for that channel.
        @param loglevel the level, messages with a level higher than this will be suppressed.
     */
    void setLevel(int loglevel);

    /** Get the log level for this channel
        @returns loglevel the level, messages with a level higher than this will be suppressed.
     */
    int getLevel();

    /** Log to a particular channel, which will be created if it does
        not exist.  You probably want to be using LOG(), however.
        @param channel the channel to log in
        @param level the level to log at.  If the logging channel
        level is lower than this level, the log message will be suppressed
        @param message the message string to print
        @internal
     */
    static void log(const char* channel, int level, const string& message);
    static void log(const string& channel, int level, const string& message);

    /** Obtain the log object for a particular channel
        @param channel the channel desired.
        @returns the log object desired, or 0 if it does not exist
    */
    static Log* getLog(const string& channel);

    /** Obtain the log object for a particular channel
        @param channel the channel desired.
        @returns the log object desired, or 0 if it does not exist
    */
    static Log* getLog(const char* channel);

    /** Add a new channel to the channel table.
        @param l the log channel
     */
    static void addChannel(Log* l);

    /** Sets the default output stream for new log objects.  The
        starting default output stream is "clog" (which is generally
        an alias for stderr.)
        @param o the output stream
    */
    static void setDefaultOutputStream(std::ostream* o);

    /** Sets the default log level for new log channels.
        @param loglevel the level, messages with a level higher than this will be suppressed.
    */
    static void setDefaultLevel(int loglevel);

    /** Returns the default log level for new log channels. */
    static int getDefaultLevel();

    /** Sets the master log level for all log objects. The master log level applies to all
        logging statements, regardless of channel name.
        @param loglevel the new level. Messages with a level higher than this will be suppressed.
    */
    static void setMasterLevel(int loglevel);

    /** Returns the master log level. */
    static int getMasterLevel();

    /** Read the environment variable VOS_LOG and set/create the
        appropriate log channels to the specified levels.
        @note This is called exactly once automatically by getLog() so
        you probably don't ever have to call this.
    */

    static void readEnvironment();

    /** Close all channels. */
    static void closeAllChannels();
};
}

#endif

---