Implementation:Ggml org Ggml Cpp smart pointers

Metadata

Field	Value
Page Type	Implementation (Utility Header)
Knowledge Sources	GGML
Domains	ML_Infrastructure, Tensor_Computing
Last Updated	2026-02-10 12:00 GMT

Overview

Provides C++ RAII smart-pointer wrappers (std::unique_ptr typedefs) for all major GGML C handle types to ensure automatic resource cleanup.

Description

ggml-cpp.h (39 lines) is a C++-only convenience header that defines custom deleter structs and std::unique_ptr typedefs for GGML's C-based object lifecycle. It prevents resource leaks by tying object lifetime to scope.

The header defines the following smart pointer types:

Core GGML types:

ggml_context_ptr -- wraps ggml_context *, calls ggml_free() on destruction
gguf_context_ptr -- wraps gguf_context *, calls gguf_free() on destruction

Allocator types:

ggml_gallocr_ptr -- wraps ggml_gallocr_t, calls ggml_gallocr_free() on destruction

Backend types:

ggml_backend_ptr -- wraps ggml_backend_t, calls ggml_backend_free()
ggml_backend_buffer_ptr -- wraps ggml_backend_buffer_t, calls ggml_backend_buffer_free()
ggml_backend_event_ptr -- wraps ggml_backend_event_t, calls ggml_backend_event_free()
ggml_backend_sched_ptr -- wraps ggml_backend_sched_t, calls ggml_backend_sched_free()

The header includes a compile-time guard (#ifndef __cplusplus) that emits a clear error if included from C code.

Usage

Include this header in C++ code that creates and manages GGML objects. The smart pointers enable exception-safe and scope-safe resource management without manual cleanup calls.

Code Reference

Source Location

GGML repo, file: include/ggml-cpp.h, 39 lines.

Signature

// Deleter structs
struct ggml_context_deleter { void operator()(ggml_context * ctx) { ggml_free(ctx); } };
struct gguf_context_deleter { void operator()(gguf_context * ctx) { gguf_free(ctx); } };
struct ggml_gallocr_deleter  { void operator()(ggml_gallocr_t galloc) { ggml_gallocr_free(galloc); } };
struct ggml_backend_deleter  { void operator()(ggml_backend_t backend) { ggml_backend_free(backend); } };
struct ggml_backend_buffer_deleter { void operator()(ggml_backend_buffer_t buf) { ggml_backend_buffer_free(buf); } };
struct ggml_backend_event_deleter  { void operator()(ggml_backend_event_t evt) { ggml_backend_event_free(evt); } };
struct ggml_backend_sched_deleter  { void operator()(ggml_backend_sched_t sched) { ggml_backend_sched_free(sched); } };

// Smart pointer typedefs
typedef std::unique_ptr<ggml_context, ggml_context_deleter> ggml_context_ptr;
typedef std::unique_ptr<gguf_context, gguf_context_deleter> gguf_context_ptr;
typedef std::unique_ptr<ggml_gallocr,  ggml_gallocr_deleter>  ggml_gallocr_ptr;
typedef std::unique_ptr<ggml_backend,  ggml_backend_deleter>  ggml_backend_ptr;
typedef std::unique_ptr<ggml_backend_buffer, ggml_backend_buffer_deleter> ggml_backend_buffer_ptr;
typedef std::unique_ptr<ggml_backend_event,  ggml_backend_event_deleter>  ggml_backend_event_ptr;
typedef std::unique_ptr<ggml_backend_sched,  ggml_backend_sched_deleter>  ggml_backend_sched_ptr;

Import

#include "ggml-cpp.h"

Dependencies

ggml.h -- core types and ggml_free()
ggml-alloc.h -- allocator types and ggml_gallocr_free()
ggml-backend.h -- backend types and free functions
gguf.h -- GGUF types and gguf_free()
<memory> -- std::unique_ptr

I/O Contract

Inputs

Parameter	Type	Required	Description
Raw pointer	various GGML handle types	Yes	Any GGML C handle pointer to be wrapped in a smart pointer.

Outputs

Output	Type	Description
Smart pointer	`std::unique_ptr<T, Deleter>`	RAII wrapper that calls the correct GGML free function on destruction.

Usage Examples

RAII Context Management

#include "ggml-cpp.h"

void inference() {
    struct ggml_init_params params = { .mem_size = 1024*1024, .no_alloc = true };
    ggml_context_ptr ctx(ggml_init(params));

    // ctx is automatically freed when it goes out of scope,
    // even if an exception is thrown
    struct ggml_tensor * t = ggml_new_tensor_1d(ctx.get(), GGML_TYPE_F32, 128);
}

RAII Backend Management

#include "ggml-cpp.h"

void run_with_backend() {
    ggml_backend_ptr backend(ggml_backend_cpu_init());
    ggml_backend_cpu_set_n_threads(backend.get(), 4);

    // Backend is freed automatically at scope exit
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment