《OGRE 3D 渲染引擎原理与架构》14.3 LogManager 单例与监听

LogManager 是全局日志仓库:它继承 Singleton 与 LogAlloc,用 std::map 管理多个 Log,第一个创建的日志自动成为默认日志,logMessage 转发到默认日志。createLog 可指定 suppressFileOutput 纯逻辑日志,供 LogListener 转发。lab 用 C++ 复现单例注册表与默认日志转发。

14.3 LogManager 单例与监听

14.1 讲了单个 Log 的内部链;这一节往上走一层——多个日志由谁管理。LogManager 是全引擎的日志仓库:一个单例、一个 std::map、一个「默认日志」概念,任何模块想记日志都从它这里拿句柄。

本章与站内既有内容的分工

14.1 是 Log 本体的过滤/输出;14.2 是异常分发;这里讲对象管理层的单例模式——站内其他系列(helio、editor)也都有单例系统管理器,OGRE 的 LogManager 是「Singleton + 注册表 + 转发」的最小可读样本。

LogManager:单例 + 日志注册表

OgreLogManager.h 里的类声明很短,关键就三块:继承关系、注册表、转发 API:

// OgreMain/include/OgreLogManager.h:class LogManager(v14.6.3 源码摘录,已删减)
    class _OgreExport LogManager : public Singleton<LogManager>, public LogAlloc
    {
    private:
        typedef std::map<String, Log*> LogList;

        /// A list of all the logs the manager can access
        LogList mLogs;

        /// The default log to which output is done
        Log* mDefaultLog;

    public:
        OGRE_AUTO_MUTEX; // public to allow external locking

        LogManager();
        ~LogManager();

        /** Creates a new log with the given name.
            @param
                name The name to give the log e.g. 'Ogre.log'
            @param
                defaultLog If true, this is the default log output will be
                sent to if the generic logging methods on this class are
                used. The first log created is always the default log unless
                this parameter is set.
        */
        Log* createLog( const String& name, bool defaultLog = false, bool debuggerOutput = true, 
            bool suppressFileOutput = false);

        /** Retrieves a log managed by this class.
        */
        Log* getLog( const String& name);

        /** Returns a pointer to the default log.
        */
        Log* getDefaultLog();

        /** Sets the passed in log as the default log.
        @return The previous default log.
        */
        Log* setDefaultLog(Log* newLog);

        /** Log a message to the default log.
        */
        void logMessage( const String& message, LogMessageLevel lml = LML_NORMAL, 
            bool maskDebug = false);

        /// @overload
        void logError(const String& message, bool maskDebug = false );
        /// @overload
        void logWarning(const String& message, bool maskDebug = false );

        /// @deprecated use setMinLogLevel()
        OGRE_DEPRECATED void setLogDetail(LoggingLevel ll);
        /// sets the minimal #LogMessageLevel for the default log
        void setMinLogLevel(LogMessageLevel lml);
    };

三个设计要点:

  • 单例:Singleton<LogManager> 模板给全引擎一个实例访问点。类注释强调启动序——Root 构造时会自动建一个 LogManager 和默认日志;若应用想从第一行就控制日志,就得先自己建 LogManager 再建 Root,Root 检测到已存在就不再覆盖。
  • 注册表:std::map<String, Log*> mLogs 用名字索引日志,createLog 注册、getLog 按名取、destroyLog 关闭移除。
  • 默认日志:mDefaultLog 指针。createLog 的注释写了关键规则——第一个创建的日志自动成为默认日志,除非显式传 defaultLog=true 覆盖。

转发 API 也全在注释里说清了:logMessage/logError/logWarning 都写到默认日志;setDefaultLog 换默认、返回旧的。这样普通模块根本不需要持有某个 Log 的指针,全局 LogManager::getSingleton().logMessage(...) 即可。

纯逻辑日志与监听转发

createLog 最后一个参数 suppressFileOutput 值得单独讲——它把「写文件」这个动作关掉,日志变成纯逻辑对象:

// OgreMain/include/OgreLogManager.h:createLog 参数注释(v14.6.3 源码摘录,已删减)
        /** @param
                suppressFileOutput If true, this is a logical rather than a physical
                log and no file output will be written. If you do this you should
                register a LogListener so log output is not lost.
        */

注释直白地给了使用指引:如果关文件输出,就应该挂一个 LogListener,否则消息在到达监听器之后就没处去了。这正好闭合 14.1 讲过的机制——Log::logMessage 里监听器先于落盘执行,所以「无文件 + 有监听器」组合下,消息经监听器转发给 GUI/网络/调试工具,不会丢。

类注释里还有一句关于启动序的实操提醒:想要「从一开始就重定向日志输出或抑制调试输出」,就先建 LogManager 再建 Root,Root 会检测到并沿用你的日志偏好。

源码定位

  • OgreMain/include/OgreLogManager.h :class LogManager : public Singleton<LogManager>, public LogAlloc、mLogs/mDefaultLog、createLog/getDefaultLog/setDefaultLog/logMessage、suppressFileOutput 参数注释

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现 LogManager 单例、注册表与默认日志转发。它与 src/14-3-log-manager-listener.cpp 逐字节一致:

// file: src/14-3-log-manager-listener.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/14-3-log-manager-listener.cpp -o bin/14-3-log-manager-listener && ./bin/14-3-log-manager-listener
//
// 复现 LogManager 单例与日志转发:
//   LogManager 是 Singleton(对应 OgreLogManager.h class LogManager : public Singleton<LogManager>);
//   createLog 注册日志并可设为默认;getDefaultLog 取默认;
//   LogManager::logMessage 转发到默认日志(对应 OgreLogManager.cpp);
//   多个日志并存:各自独立过滤与缓冲。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <string>
#include <vector>

namespace ogre_repro {

enum LogMessageLevel { LML_NORMAL = 2, LML_WARNING = 3 };

// 极简 Log(带名字与内容缓冲)
class Log {
 public:
  explicit Log(const std::string& name) : mName(name) {}
  void logMessage(const std::string& message, LogMessageLevel lml) {
    if (lml >= mLogLevel) mContent += mName + ": " + message + "\n";
  }
  void setLogLevel(LogMessageLevel l) { mLogLevel = l; }
  const std::string& getName() const { return mName; }
  std::string mContent;

 private:
  std::string mName;
  LogMessageLevel mLogLevel = LML_NORMAL;
};

// 对应 LogManager:单例 + 日志注册表 + 默认日志
class LogManager {
 public:
  static LogManager& getSingleton() {
    static LogManager instance;
    return instance;
  }

  // 对应 LogManager::createLog:注册并可设为默认
  Log* createLog(const std::string& name, bool defaultLog) {
    mLogs.push_back(new Log(name));
    Log* l = mLogs.back();
    if (defaultLog) mDefaultLog = l;
    return l;
  }
  // 对应 LogManager::getDefaultLog
  Log* getDefaultLog() { return mDefaultLog; }
  // 对应 LogManager::logMessage:转发到默认日志
  void logMessage(const std::string& message, LogMessageLevel lml) {
    if (mDefaultLog) mDefaultLog->logMessage(message, lml);
  }

 private:
  LogManager() {}
  std::vector<Log*> mLogs;
  Log* mDefaultLog = nullptr;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  LogManager& mgr = LogManager::getSingleton();

  // 两个日志,第一个为默认
  Log* mainLog = mgr.createLog("Ogre.log", true);
  Log* secondLog = mgr.createLog("Network.log", false);
  CHECK(mgr.getDefaultLog() == mainLog);

  // logMessage 转发到默认日志
  mgr.logMessage("start", LML_NORMAL);
  CHECK(mainLog->mContent == "Ogre.log: start\n");
  CHECK(secondLog->mContent.empty());

  // 直接向非默认日志写
  secondLog->logMessage("connect", LML_NORMAL);
  CHECK(secondLog->mContent == "Network.log: connect\n");

  // 各自独立过滤:第三个日志级别设成 WARNING,NORMAL 消息被过滤
  Log* thirdLog = mgr.createLog("Debug.log", false);
  thirdLog->setLogLevel(LML_WARNING);
  thirdLog->logMessage("verbose", LML_NORMAL);
  CHECK(thirdLog->mContent.empty());

  return lab::report("14-3 日志与异常:LogManager 单例与监听");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 5/5 通过。

小结

  • LogManager : public Singleton<LogManager>, public LogAlloc,全引擎日志的唯一入口。
  • std::map<String, Log*> mLogs 按名注册日志;第一个创建的日志自动成为默认日志。
  • logMessage/logError/logWarning 一律转发到默认日志,普通模块无需持有 Log 指针。
  • suppressFileOutput=true 建纯逻辑日志,须配合 LogListener 承接输出,避免消息丢失。
  • 启动序:先建 LogManager 再建 Root,可完全接管日志偏好。

阅读导航:上一节:14.2 异常体系 · 下一节:15.1 最小的 Root 启动 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图