feat(devtools): IMC flow monitor, per-module memory attribution, log stream panels

Author: doyaGu

include/bml_imc_bus.h

@@ -403,6 +403,69 @@ typedef BML_Result (*PFN_BML_ImcGetTopicName)(BML_Context ctx,
                                               size_t buffer_size,
                                               size_t *out_length);
 
+/* ========================================================================
+ * Message Flow Monitoring APIs
+ * ======================================================================== */
+
+/**
+ * @brief Trace record for a published message.
+ *
+ * Captures metadata about a message at publish time for flow monitoring.
+ */
+typedef struct BML_ImcMessageTrace {
+    size_t struct_size;         /**< sizeof(BML_ImcMessageTrace), must be first */
+    BML_TopicId topic;          /**< Topic ID */
+    BML_Mod owner;              /**< Publishing module */
+    uint64_t timestamp_qpc;     /**< QueryPerformanceCounter timestamp */
+    size_t payload_size;        /**< Size of payload in bytes */
+    uint32_t payload_type_id;   /**< Payload type ID */
+    uint32_t priority;          /**< Message priority */
+    uint32_t flags;             /**< Message flags */
+} BML_ImcMessageTrace;
+
+/**
+ * @brief Callback invoked when a message is published.
+ *
+ * Fired from owner-variant publish methods (Publish/PublishEx/PublishBuffer/
+ * PublishInterceptable/PublishState) after validation but before dispatch.
+ * Not invoked for internal publishes or non-owner variants.
+ *
+ * @param[in] trace    Trace record with message metadata
+ * @param[in] user_data Opaque pointer provided at registration
+ *
+ * @threadsafe Yes (invoked from publish path)
+ * @warning Must be fast and non-blocking. Do not call IMC Pump from tap.
+ */
+typedef void (*BML_ImcMessageTap)(const BML_ImcMessageTrace *trace, void *user_data);
+
+/**
+ * @brief Register a message tap for flow monitoring.
+ *
+ * Only one tap can be active at a time. Overwrites any previous tap.
+ * Use for DevTools, debuggers, or telemetry systems.
+ *
+ * @param[in] owner     Module handle (owner of tap)
+ * @param[in] tap       Tap callback (NULL to unregister)
+ * @param[in] user_data Opaque pointer passed to tap
+ * @return BML_RESULT_OK on success
+ *
+ * @threadsafe Yes
+ */
+typedef BML_Result (*PFN_BML_ImcRegisterMessageTap)(BML_Mod owner,
+                                                     BML_ImcMessageTap tap,
+                                                     void *user_data);
+
+/**
+ * @brief Unregister the current message tap.
+ *
+ * @param[in] owner Module handle (must match registration owner)
+ * @return BML_RESULT_OK on success
+ * @return BML_RESULT_NOT_FOUND if no tap registered or owner mismatch
+ *
+ * @threadsafe Yes
+ */
+typedef BML_Result (*PFN_BML_ImcUnregisterMessageTap)(BML_Mod owner);
+
 /* ========================================================================
  * Bus Interface Vtable
  * ======================================================================== */
@@ -431,6 +494,8 @@ typedef struct BML_ImcBusInterface {
     PFN_BML_ImcResetStats ResetStats;
     PFN_BML_ImcGetTopicInfo GetTopicInfo;
     PFN_BML_ImcGetTopicName GetTopicName;
+    PFN_BML_ImcRegisterMessageTap RegisterMessageTap;
+    PFN_BML_ImcUnregisterMessageTap UnregisterMessageTap;
 } BML_ImcBusInterface;
 
 BML_END_CDECLS

include/bml_logging.h

@@ -55,6 +55,16 @@ typedef void (*BML_LogSinkDispatchFn)(BML_Context ctx, const BML_LogMessageInfo
  */
 typedef void (*BML_LogSinkShutdownFn)(void *user_data);
 
+/**
+ * @brief Log listener callback type (non-exclusive, multiple allowed)
+ * @param ctx BML context
+ * @param info Log message information
+ * @param user_data User-provided context from registration
+ * @note This callback is invoked for every log message, independent of sink override.
+ *       The callback should be fast and avoid blocking operations.
+ */
+typedef void (*BML_LogListenerFn)(BML_Context ctx, const BML_LogMessageInfo *info, void *user_data);
+
 /**
  * @brief Flags for log sink override behavior
  */
@@ -123,6 +133,30 @@ typedef void (*PFN_BML_LogVa)(BML_Mod owner,
  */
 typedef void (*PFN_BML_SetLogFilter)(BML_Mod owner, BML_LogSeverity minimum_level);
 
+/**
+ * @brief Add a log listener callback
+ * @param owner Module registering the listener
+ * @param listener Callback function to receive log messages
+ * @param user_data User context passed to the callback
+ * @return BML_RESULT_OK on success
+ * @return BML_RESULT_INVALID_ARGUMENT if listener is NULL
+ * @threadsafe Yes
+ */
+typedef BML_Result (*PFN_BML_AddLogListener)(BML_Mod owner,
+                                             BML_LogListenerFn listener,
+                                             void *user_data);
+
+/**
+ * @brief Remove a log listener callback
+ * @param owner Module that registered the listener
+ * @param listener Callback function to remove
+ * @return BML_RESULT_OK on success
+ * @return BML_RESULT_NOT_FOUND if listener was not registered
+ * @threadsafe Yes
+ */
+typedef BML_Result (*PFN_BML_RemoveLogListener)(BML_Mod owner,
+                                                BML_LogListenerFn listener);
+
 typedef enum BML_LogCreateFlags {
     BML_LOG_CREATE_ALLOW_TAGS   = 1u << 0,
     BML_LOG_CREATE_ALLOW_FILTER = 1u << 1,
@@ -155,6 +189,8 @@ typedef struct BML_CoreLoggingInterface {
     PFN_BML_SetLogFilter SetLogFilter;
     PFN_BML_RegisterLogSinkOverride RegisterSinkOverride;
     PFN_BML_ClearLogSinkOverride ClearSinkOverride;
+    PFN_BML_AddLogListener AddLogListener;
+    PFN_BML_RemoveLogListener RemoveLogListener;
 } BML_CoreLoggingInterface;
 
 

include/bml_memory.h

@@ -191,6 +191,46 @@ typedef struct BML_MemoryStats {
  */
 typedef BML_Result (*PFN_BML_GetMemoryStats)(BML_Context ctx, BML_MemoryStats *out_stats);
 
+/* ========== Per-module Memory Tracking ========== */
+
+/**
+ * @brief Per-module memory statistics (for diagnostic enumeration)
+ */
+typedef struct BML_ModuleMemoryStats {
+    size_t struct_size;            /**< sizeof(BML_ModuleMemoryStats) */
+    const char *module_id;         /**< Stable pointer, valid during callback */
+    uint64_t total_allocated;      /**< Bytes currently held by this module */
+    uint64_t peak_allocated;       /**< Peak bytes held */
+    uint64_t alloc_count;          /**< Lifetime allocation count */
+    uint64_t free_count;           /**< Lifetime free count */
+    uint64_t active_alloc_count;   /**< Currently live allocations */
+} BML_ModuleMemoryStats;
+
+#define BML_MODULE_MEMORY_STATS_INIT { sizeof(BML_ModuleMemoryStats), NULL, 0, 0, 0, 0, 0 }
+
+/**
+ * @brief Callback for per-module memory enumeration
+ */
+typedef void (*BML_EnumerateModuleMemoryFn)(
+    const BML_ModuleMemoryStats *stats, void *user_data);
+
+/**
+ * @brief Enable/disable per-module memory tracking.
+ * When enabled, each alloc/free is attributed to the calling module.
+ * Adds ~100-200ns overhead per allocation.
+ * @threadsafe Yes
+ */
+typedef BML_Result (*PFN_BML_EnableModuleMemoryTracking)(
+    BML_Context ctx, BML_Bool enable);
+
+/**
+ * @brief Enumerate per-module memory statistics.
+ * Calls callback once per tracked module.
+ * @threadsafe Yes (snapshot under lock)
+ */
+typedef BML_Result (*PFN_BML_EnumerateModuleMemory)(
+    BML_Context ctx, BML_EnumerateModuleMemoryFn callback, void *user_data);
+
 typedef struct BML_CoreMemoryInterface {
     BML_InterfaceHeader header;
     BML_Context Context;
@@ -205,6 +245,8 @@ typedef struct BML_CoreMemoryInterface {
     PFN_BML_MemoryPoolFree MemoryPoolFree;
     PFN_BML_MemoryPoolDestroy MemoryPoolDestroy;
     PFN_BML_GetMemoryStats GetMemoryStats;
+    PFN_BML_EnableModuleMemoryTracking EnableModuleMemoryTracking;
+    PFN_BML_EnumerateModuleMemory EnumerateModuleMemory;
 } BML_CoreMemoryInterface;
 
 

modules/BML_DevTools/locale/en.toml

@@ -9,6 +9,9 @@ imc = "IMC"
 interfaces = "Interfaces"
 hooks = "Hooks"
 modules = "Modules"
+imc_flow = "IMC Flow"
+module_memory = "Module Memory"
+log_stream = "Log Stream"
 
 [column]
 id = "ID"
@@ -25,6 +28,31 @@ target = "Target"
 address = "Address"
 priority = "Priority"
 module_id = "Module ID"
+time = "Time"
+topic = "Topic"
+source = "Source"
+size = "Size"
+rate = "Rate/s"
+allocated = "Allocated"
+peak = "Peak"
+active = "Active"
+trend = "Trend"
+level = "Level"
+module = "Module"
+tag = "Tag"
+message = "Message"
 
 [status]
 conflict = "CONFLICT"
+
+[label]
+feature_unavailable = "Feature requires BML >= 0.4.1"
+throughput = "Throughput"
+pause = "Pause"
+clear = "Clear"
+filter = "Filter"
+tracking_active = "Per-module tracking active"
+tracking_note = "Tracking adds ~100-200ns overhead per allocation"
+total_across = "Total: %.2f MB across %u modules"
+severity_filter = "Severity"
+auto_scroll = "Auto-scroll"

modules/BML_DevTools/locale/zh-CN.toml

@@ -9,6 +9,9 @@ imc = "IMC 消息总线"
 interfaces = "接口注册表"
 hooks = "Hook 注册表"
 modules = "已加载模块"
+imc_flow = "IMC 消息流"
+module_memory = "模块内存"
+log_stream = "日志流"
 
 [column]
 id = "ID"
@@ -25,6 +28,31 @@ target = "目标"
 address = "地址"
 priority = "优先级"
 module_id = "模块 ID"
+time = "时间"
+topic = "主题"
+source = "来源"
+size = "大小"
+rate = "速率/秒"
+allocated = "已分配"
+peak = "峰值"
+active = "活跃"
+trend = "趋势"
+level = "级别"
+module = "模块"
+tag = "标签"
+message = "消息"
 
 [status]
 conflict = "冲突"
+
+[label]
+feature_unavailable = "此功能需要 BML >= 0.4.1"
+throughput = "吞吐量"
+pause = "暂停"
+clear = "清除"
+filter = "过滤"
+tracking_active = "模块内存跟踪已启用"
+tracking_note = "跟踪每次分配增加约 100-200ns 开销"
+total_across = "合计: %.2f MB, 共 %u 个模块"
+severity_filter = "严重度"
+auto_scroll = "自动滚动"

modules/BML_DevTools/src/ConcurrentRingBuffer.h

@@ -0,0 +1,77 @@
+#ifndef BML_DEVTOOLS_CONCURRENT_RING_BUFFER_H
+#define BML_DEVTOOLS_CONCURRENT_RING_BUFFER_H
+
+#include <atomic>
+#include <cstddef>
+#include <new>
+#include <type_traits>
+
+namespace devtools {
+
+/// Lock-free bounded MPSC (multi-producer, single-consumer) ring buffer.
+/// Uses Vyukov sequence-based algorithm for safe concurrent writes.
+/// N must be a power of two.
+template <typename T, size_t N>
+class ConcurrentRingBuffer {
+    static_assert((N & (N - 1)) == 0, "N must be power of 2");
+    static_assert(N >= 2, "N must be at least 2");
+    static constexpr size_t kMask = N - 1;
+
+    struct Slot {
+        std::atomic<size_t> sequence;
+        T data;
+    };
+
+    alignas(64) Slot m_Slots[N];
+    alignas(64) std::atomic<size_t> m_WriteHead{0};
+    alignas(64) size_t m_ReadTail{0};
+
+public:
+    ConcurrentRingBuffer() {
+        for (size_t i = 0; i < N; ++i)
+            m_Slots[i].sequence.store(i, std::memory_order_relaxed);
+    }
+
+    bool TryPush(const T &value) {
+        size_t pos = m_WriteHead.load(std::memory_order_relaxed);
+        for (;;) {
+            Slot &slot = m_Slots[pos & kMask];
+            size_t seq = slot.sequence.load(std::memory_order_acquire);
+            auto diff = static_cast<intptr_t>(seq) - static_cast<intptr_t>(pos);
+            if (diff == 0) {
+                if (m_WriteHead.compare_exchange_weak(
+                        pos, pos + 1, std::memory_order_relaxed)) {
+                    slot.data = value;
+                    slot.sequence.store(pos + 1, std::memory_order_release);
+                    return true;
+                }
+            } else if (diff < 0) {
+                return false;
+            } else {
+                pos = m_WriteHead.load(std::memory_order_relaxed);
+            }
+        }
+    }
+
+    size_t Drain(T *out, size_t max_count) {
+        size_t count = 0;
+        while (count < max_count) {
+            Slot &slot = m_Slots[m_ReadTail & kMask];
+            size_t seq = slot.sequence.load(std::memory_order_acquire);
+            auto diff = static_cast<intptr_t>(seq)
+                      - static_cast<intptr_t>(m_ReadTail + 1);
+            if (diff == 0) {
+                out[count++] = std::move(slot.data);
+                slot.sequence.store(m_ReadTail + N, std::memory_order_release);
+                ++m_ReadTail;
+            } else {
+                break;
+            }
+        }
+        return count;
+    }
+};
+
+} // namespace devtools
+
+#endif // BML_DEVTOOLS_CONCURRENT_RING_BUFFER_H

modules/BML_DevTools/src/DevToolsMod.cpp

@@ -26,6 +26,9 @@
 #include "InterfacePanel.h"
 #include "HookPanel.h"
 #include "ModulePanel.h"
+#include "ImcFlowPanel.h"
+#include "ModuleMemoryPanel.h"
+#include "LogStreamPanel.h"
 
 namespace {
 
@@ -47,6 +50,9 @@ class DevToolsMod : public bml::Module {
         m_Panels.push_back(std::make_unique<devtools::InterfacePanel>());
         m_Panels.push_back(std::make_unique<devtools::HookPanel>());
         m_Panels.push_back(std::make_unique<devtools::ModulePanel>());
+        m_Panels.push_back(std::make_unique<devtools::ImcFlowPanel>());
+        m_Panels.push_back(std::make_unique<devtools::ModuleMemoryPanel>());
+        m_Panels.push_back(std::make_unique<devtools::LogStreamPanel>());
     }
 
     void RefreshAll() {
@@ -102,7 +108,12 @@ class DevToolsMod : public bml::Module {
             if (!event || event->repeat) return;
             if (event->key_code == 0x58) {
                 m_Visible = !m_Visible;
-                if (m_Visible) RefreshAll();
+                if (m_Visible) {
+                    RefreshAll();
+                    for (auto &p : m_Panels) p->OnShow(Services());
+                } else {
+                    for (auto &p : m_Panels) p->OnHide(Services());
+                }
             }
         });
 
@@ -114,6 +125,9 @@ class DevToolsMod : public bml::Module {
     }
 
     void OnDetach() override {
+        if (m_Visible) {
+            for (auto &p : m_Panels) p->OnHide(Services());
+        }
         m_Panels.clear();
         m_Subs.Clear();
         m_DrawReg.Reset();