Resource Management

VSAG lets you take control of the memory and threads it uses. This page covers Allocator (custom memory management), ThreadPool (custom concurrency), Resource (a bundle of the two shared by an Engine), the process-wide Options singleton, and the pluggable Logger.

Runnable samples: examples/cpp/201_custom_allocator.cpp, 202_custom_logger.cpp, and 203_custom_thread_pool.cpp. See also Memory Management and Extensibility.

Allocator

Declared in vsag/allocator.h. An abstract interface for custom memory management. Implement it to route all of an index’s allocations through your own pool, arena, or accounting layer, then pass it to Factory::CreateIndex or a 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);  // Allocate + construct
    template <typename T> void Delete(T* p);                          // destruct + Deallocate
};

An allocator passed to an index must outlive that index. VSAG’s built-in allocator is available via Engine::CreateDefaultAllocator.

ThreadPool

Declared in vsag/thread_pool.h. An abstract task executor. Supply your own to make VSAG share your application’s threads instead of spawning its own.

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;
};

A ready-made pool can be created with Engine::CreateThreadPool.

Resource

Declared in vsag/resource.h. A Resource bundles an Allocator and a ThreadPool so that an Engine — and every index it creates — can share them.

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();  // default allocator, no thread pool

    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

Declared in vsag/options.h. A process-wide singleton for global configuration, accessed via Options::Instance(). Thread-safe. Option is a type alias for Options.

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

Logger

Declared in vsag/logger.h. An abstract logging sink. Implement it and register it via Options::set_logger to route VSAG’s log output through your application’s logging system.

The built-in logger defaults to info. Set VSAG_LOG_LEVEL before the built-in logger is created to choose trace, debug, info, warn/warning, error, critical, or off. Invalid values are ignored and keep the default level. An explicit SetLevel call still overrides the environment-derived level.

Startup init banner

VSAG logs a startup initialization banner when vsag::init() runs. To suppress that banner, set VSAG_SUPPRESS_INIT_BANNER before starting the process. This is useful for tests, CI jobs, or applications that need quieter startup logs.

Truthy values are 1, on, and true; matching for on and true is ASCII case-insensitive, so ON, On, and TRUE also work. Other values leave the banner enabled.

Set the variable before process start. VSAG also runs vsag::init() during static initialization, so setting the variable later from inside the process cannot suppress the first banner.

The banner includes an instance spec value such as 48C503G, combining the cpuinfo core count with total physical memory. Memory is reported in whole GiB using floor division by 1024^3; if the platform query fails, the memory portion is shown as ?G. SIMD lines, including neon and sve, retain their existing distribution/platform/using capability semantics.

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;
};

See examples/cpp/202_custom_logger.cpp.

See also

• Factory & Engine — how Engine consumes a Resource.
• Index — per-call allocators on retrieval and search methods.
• Search Request & Filters — the per-search allocator field.