资源管理

VSAG 允许你掌控它所使用的内存与线程。本页介绍 Allocator（自定义内存管理）、 ThreadPool（自定义并发）、Resource（由 Engine 共享的两者打包）、进程级的 Options 单例，以及可插拔的 Logger。

可运行示例：examples/cpp/201_custom_allocator.cpp、202_custom_logger.cpp、 203_custom_thread_pool.cpp。另见 内存管理 与 可扩展性。

Allocator

声明于 vsag/allocator.h。用于自定义内存管理的抽象接口。实现它即可把索引的全部分配路由到你自己的池、 arena 或记账层，然后把它传给 Factory::CreateIndex 或一个 Resource。

class Allocator {
public:
    virtual std::string Name() = 0;
    virtual void* Allocate(uint64_t size) = 0;
    virtual void Deallocate(void* p) = 0;
    virtual void* Reallocate(void* p, uint64_t size) = 0;

    template <typename T, typename... Args> T* New(Args&&... args);  // 分配 + 构造
    template <typename T> void Delete(T* p);                          // 析构 + 释放
};

传给索引的 allocator 必须比该索引活得更久。VSAG 内置 allocator 可通过 Engine::CreateDefaultAllocator 获取。

ThreadPool

声明于 vsag/thread_pool.h。一个抽象的任务执行器。提供你自己的实现，即可让 VSAG 共享你应用的线程，而 不是自行创建。

class ThreadPool {
public:
    virtual void WaitUntilEmpty() = 0;
    virtual void SetQueueSizeLimit(std::uint64_t limit) = 0;
    virtual void SetPoolSize(std::uint64_t limit) = 0;
    virtual std::future<void> Enqueue(std::function<void(void)> task) = 0;
};

现成的线程池可通过 Engine::CreateThreadPool 创建。

Resource

声明于 vsag/resource.h。Resource 把一个 Allocator 与一个 ThreadPool 打包，使一个 Engine —— 及其创建的每个索引 —— 都能共享它们。

class Resource {
public:
    explicit Resource(Allocator* allocator, ThreadPool* thread_pool);
    explicit Resource(const std::shared_ptr<Allocator>& allocator,
                      const std::shared_ptr<ThreadPool>& thread_pool);
    explicit Resource();  // 默认 allocator，无线程池

    std::shared_ptr<Allocator> GetAllocator() const;
    std::shared_ptr<ThreadPool> GetThreadPool() const;
};

auto alloc = vsag::Engine::CreateDefaultAllocator();
auto pool = vsag::Engine::CreateThreadPool(4).value();
vsag::Resource resource(alloc, pool);
vsag::Engine engine(&resource);
auto index = engine.CreateIndex("hgraph", params);

Options

声明于 vsag/options.h。用于全局配置的进程级单例，通过 Options::Instance() 访问。线程安全。Option 是 Options 的类型别名。

vsag::Options::Instance().set_num_threads_building(8);
vsag::Options::Instance().set_logger(&my_logger);

Logger

声明于 vsag/logger.h。一个抽象的日志汇。实现它并通过 Options::set_logger 注册，即可把 VSAG 的日志 输出路由到你应用的日志系统。

内置 logger 默认使用 info。在内置 logger 创建前设置 VSAG_LOG_LEVEL，可选择 trace、 debug、info、warn/warning、error、critical 或 off。无效值会被忽略，并保留默认等级。 显式调用 SetLevel 仍会覆盖从环境变量得到的等级。

启动 init banner

VSAG 会在 vsag::init() 运行时输出启动初始化 banner。如需隐藏该 banner， 请在进程启动前设置 VSAG_SUPPRESS_INIT_BANNER。这适用于测试、CI 任务， 或需要更安静启动日志的应用。

可识别的真值为 1、on 和 true；on 与 true 按 ASCII 大小写不敏感匹配， 因此 ON、On 和 TRUE 也有效。其他值会保留 banner 输出。

请务必在进程启动前设置该变量。VSAG 也会在静态初始化阶段运行 vsag::init()，因此在进程内部稍后再设置该变量，无法隐藏首次 banner。

banner 包含类似 48C503G 的 instance spec 值，将 cpuinfo 获取的核心数与物理内存总量合并展示。 内存使用 1024^3 字节进行整 GiB 向下取整；如果平台查询失败，内存部分显示为 ?G。包括 neon 和 sve 在内的 SIMD 行，仍保持原有的 distribution/platform/using 能力语义。

VSAG_SUPPRESS_INIT_BANNER=1 ./your_vsag_app
VSAG_SUPPRESS_INIT_BANNER=true ./your_vsag_test

class Logger {
public:
    enum Level : int {
        kTRACE = 0, kDEBUG = 1, kINFO = 2, kWARN = 3, kERR = 4, kCRITICAL = 5, kOFF = 6, kN_LEVELS
    };

    virtual void SetLevel(Level log_level) = 0;
    virtual void Trace(const std::string& msg) = 0;
    virtual void Debug(const std::string& msg) = 0;
    virtual void Info(const std::string& msg) = 0;
    virtual void Warn(const std::string& msg) = 0;
    virtual void Error(const std::string& msg) = 0;
    virtual void Critical(const std::string& msg) = 0;
};

见 examples/cpp/202_custom_logger.cpp。

参见

• Factory 与 Engine —— Engine 如何消费 Resource。
• Index —— 取回与搜索方法上的逐次调用 allocator。
• 搜索请求与过滤器 —— 逐次搜索 allocator 字段。