Buffers and Zero-Copy

The problem it solves

Lesson 01 established the cost of the object model: a list of a million floats is a million heap objects. A C extension that wants to process bulk numeric or binary data cannot afford to unbox them one at a time — the unboxing is the cost.

The buffer protocol (PEP 3118) is CPython's answer. An object that owns a flat block of memory — bytes, bytearray, array.array, mmap, a NumPy array, your own type — can expose that block directly. A consumer gets a pointer, a length, and a description of the layout, and then works in plain C. No copy, and no Python objects involved in the inner loop.

It is also the only mechanism that makes "release the interpreter and compute" (Lesson 10) sound: acquiring a buffer pins the memory, so the pointer stays valid while you are detached.

Py_buffer

typedef struct {
    void       *buf;         /* pointer to the start of the logical data */
    PyObject   *obj;         /* the exporter -- a STRONG reference you own */
    Py_ssize_t  len;         /* total bytes = product(shape) * itemsize    */
    Py_ssize_t  itemsize;    /* bytes per element                          */
    int         readonly;    /* 1 if you must not write                    */
    int         ndim;        /* number of dimensions; 0 means a scalar     */
    char       *format;      /* struct-module syntax, e.g. "d", "i", "B"   */
    Py_ssize_t *shape;       /* ndim entries, or NULL                      */
    Py_ssize_t *strides;     /* ndim entries in BYTES, or NULL             */
    Py_ssize_t *suboffsets;  /* ndim entries, or NULL (pointer arrays)     */
    void       *internal;    /* exporter's private data -- do not touch    */
} Py_buffer;

Which of those fields are filled depends on what you asked for. The exporter fills only what your request flags permit, which is how a simple consumer avoids having to handle strided multi-dimensional layouts.

Consuming a buffer

Py_buffer view;
if (PyObject_GetBuffer(obj, &view, PyBUF_C_CONTIGUOUS | PyBUF_FORMAT) < 0) {
    return NULL;            /* BufferError already set: obj cannot comply */
}

... use view.buf, view.len, view.itemsize ...

PyBuffer_Release(&view);    /* mandatory, on every path */

Three properties of this pairing:

• PyObject_GetBuffer sets view.obj to a strong reference to the exporter. PyBuffer_Release drops it. The pairing is exactly like malloc/free, and leaking a view leaks the object.
• If it fails it raises BufferError and sets view.obj to NULL. Do not release a failed view.
• While the view is held, the exporter is obliged to keep the memory at that address. bytearray, for instance, refuses to resize while exported — that is what makes the pin real.

Request flags: ask for the least you can handle

The flags are a contract in both directions. You state what you can cope with; the exporter either complies or refuses.

Validating what you got

if (view.ndim != 1) {
    PyBuffer_Release(&view);
    PyErr_SetString(PyExc_ValueError, "expected a 1-D buffer");
    return NULL;
}
if (view.format == NULL || strcmp(view.format, "d") != 0) {
    PyBuffer_Release(&view);
    PyErr_SetString(PyExc_TypeError, "expected a buffer of C doubles ('d')");
    return NULL;
}
Py_ssize_t n = view.shape[0];        /* or view.len / view.itemsize */

format uses the struct module's syntax: "B" unsigned char, "b" signed char, "h"/"i"/"l"/"q" integers, "f"/"d" floats, with "<"/">" prefixes for byte order. Do not skip this check: a caller passing an int32 array where you expect float64 will otherwise produce garbage with no error.

The shortcut through argument parsing

Lesson 06's format units s*, y* and w* acquire a buffer for you (w* demanding a writable one). They are convenient, but they request a permissive layout, so you still validate — and you still must release:

Py_buffer data;
if (!PyArg_ParseTuple(args, "y*", &data)) return NULL;
...
PyBuffer_Release(&data);

Strides, when you do accept them

With PyBUF_STRIDES, element (i, j) lives at (char *)view.buf + i*strides[0] + j*strides[1]. Strides are in bytes, not elements, and may be negative (a reversed slice). PyBuffer_GetPointer(&view, indices) does the arithmetic for you, and PyBuffer_IsContiguous(&view, 'C') lets you take a fast path when the strides happen to be contiguous anyway.

Exporting a buffer from your own type

Two slots, in a PyBufferProcs struct hung off tp_as_buffer (or Py_bf_getbuffer / Py_bf_releasebuffer for a heap type):

static int
Block_getbuffer(PyObject *op, Py_buffer *view, int flags)
{
    BlockObject *self = (BlockObject *)op;

    if ((flags & PyBUF_WRITABLE) && self->readonly) {
        PyErr_SetString(PyExc_BufferError, "block is read-only");
        view->obj = NULL;
        return -1;
    }

    /* PyBuffer_FillInfo handles the common 1-D byte-oriented case: it fills
       every field, honours the flags, and increfs the exporter for you. */
    return PyBuffer_FillInfo(view, op, self->data, self->nbytes,
                             self->readonly, flags);
}

static void
Block_releasebuffer(PyObject *op, Py_buffer *view)
{
    BlockObject *self = (BlockObject *)op;
    self->exports--;        /* only needed if you must track outstanding views */
}

static PyType_Slot Block_slots[] = {
    {Py_bf_getbuffer,     Block_getbuffer},
    {Py_bf_releasebuffer, Block_releasebuffer},
    ...
};

PyBuffer_FillInfo is the right tool unless you are exporting a multi-dimensional layout.

Obligations of an exporter:

• On success, set view->obj to a new strong reference to yourself. PyBuffer_FillInfo does this.
• On failure, set view->obj = NULL, raise BufferError, return −1.
• Keep the memory at a fixed address for as long as any view exists. If your object can be resized or reallocated, count outstanding exports in bf_releasebuffer and refuse the operation while the count is nonzero — which is exactly what bytearray does.
• bf_releasebuffer is optional. Omit it if you have nothing to track. Do not free anything in it: the caller's PyBuffer_Release handles the refcount.

Buffers and the detached region

This is where the lesson pays off. A pinned buffer is one of the very few things you may legitimately touch while detached:

const double *p = (const double *)view.buf;
Py_ssize_t n = view.shape[0];

Py_BEGIN_ALLOW_THREADS
for (Py_ssize_t i = 0; i < n; i++) out[i] = p[i] * k;
Py_END_ALLOW_THREADS

Where this sits relative to NumPy

NumPy arrays export the buffer protocol, so everything above works on them and is the right choice when you want to accept "any array-like" without depending on NumPy at build time. If instead you are writing a NumPy-specific extension, NumPy has its own richer C API (PyArray_*) with dtypes, broadcasting and ufuncs that the buffer protocol does not model.

For zero-copy exchange with GPU frameworks and other array libraries, the current lingua franca is DLPack (exposed in Python as __dlpack__), which handles device memory that the buffer protocol cannot describe. Know it exists; the buffer protocol remains the right answer for CPU memory.

import array

a = array.array("d", [1.0, 2.0, 3.0, 4.0])
m = memoryview(a)
print(m.format, m.itemsize, m.ndim, m.shape, m.strides, m.readonly, m.c_contiguous)

# Zero-copy mutation through a view of a mutable object:
ba = bytearray(b"hello")
mv = memoryview(ba)
mv[0] = ord("H")
print(ba)

# The pin is real: resizing while exported is refused.
try:
    ba.extend(b"!!")
except BufferError as e:
    print("BufferError:", e)
del mv
ba.extend(b"!!")
print(ba)

# Strides and non-contiguity, the case your C code must reject or handle:
try:
    import numpy as np
    arr = np.arange(12, dtype=np.float64).reshape(3, 4)
    print(memoryview(arr).strides, memoryview(arr).c_contiguous)
    print(memoryview(arr.T).strides, memoryview(arr.T).c_contiguous)
except ImportError:
    pass

Further reading

• C API — Buffer Protocol. Every field, every flag, and the exporter/consumer contract.
• PEP 3118 — Revising the buffer protocol. The design rationale, including why strides and suboffsets exist.
• memoryview. The Python-level view of the same protocol; invaluable for exploration and testing.
• NumPy array interface and DLPack, for the array-library ecosystem beyond CPU memory.