Протокол буферизации

Структура буфера

Структуры буферов (или просто «буферы») полезны для экспонирования двоичных данных из другого объекта для программиста Python. Они также могут использоваться как механизм обрезки без копирования. Используя возможность ссылаться на блок памяти, можно довольно легко экспонировать любые данные программисту Python. Память может представлять собой большой, постоянный массив в расширении C, сырой блок памяти для манипулирования перед передачей в библиотеку операционной системы или для передачи структурированных данных в их родном, внутрипамятьном формате.

В отличие от большинства типов данных, экспонируемых интерпретатором Python, буферы не являются указателями PyObject, а скорее простыми структурами C. Это позволяет создавать и копировать их очень просто. Если нужен обобщённый обертка вокруг буфера, можно создать объект memoryview.

Краткие инструкции по написанию экспортирующего объекта см. в Структура объекта буфера. Для получения буфера см. PyObject_GetBuffer().

Py_buffer

void *buf

Указатель на начало логической структуры, описываемой полями буфера. Он может указывать на любое место в базовом физическом блоке памяти экспортера. Например, при отрицательных значениях strides значение может указывать на конец блока памяти.

Для смежных массивов значение указывает на начало блока памяти.

void *obj

Новая ссылка на экспортирующий объект. Ссылка принадлежит потребителю и автоматически декрементируется и устанавливается в NULL функцией PyBuffer_Release(). Поле эквивалентно возвращаемому значению любой стандартной функции C-API.

В качестве особого случая для временных буферов, обернутых PyMemoryView_FromBuffer() или PyBuffer_FillInfo(), это поле равно NULL. В общем случае экспортирующие объекты НЕ должны использовать эту схему.

Py_ssize_t len

product(shape) * itemsize. Для смежных массивов это длина базового блока памяти. Для несмежных массивов это длина, которую имела бы логическая структура, если бы она была скопирована в смежную.

Доступ к ((char *)buf)[0] up to ((char *)buf)[len-1] допустим только в том случае, если буфер был получен запросом, гарантирующим смежность. В большинстве случаев таким запросом будет PyBUF_SIMPLE или PyBUF_WRITABLE.

int readonly

Указатель на то, является ли буфер только для чтения. Это поле управляется флагом PyBUF_WRITABLE.

Py_ssize_t itemsize

Размер элемента в байтах. Соответствует значению struct.calcsize(), вызываемому для значений, не являющихся NULL format.

Важное исключение: если потребитель запрашивает буфер без флага PyBUF_FORMAT, format будет установлено в NULL, но itemsize по-прежнему сохраняет значение для исходного формата.

Если shape присутствует, равенство product(shape) * itemsize == len сохраняется, и потребитель может использовать itemsize для навигации по буферу.

Если shape присутствует в результате запроса PyBUF_SIMPLE или PyBUF_WRITABLE, потребитель должен игнорировать itemsize и предполагать itemsize == 1.

const char *format

Строка с завершением NUL в стиле синтаксиса модуля struct, описывающая содержимое одного элемента. Если это NULL, предполагается "B" (беззнаковые байты).

Это поле управляется флагом PyBUF_FORMAT.

int ndim

Число измерений, которые память представляет в виде n-мерного массива. Если это 0, buf указывает на единственный элемент, представляющий скаляр. В этом случае shape, strides и suboffsets должны быть NULL.

Макросом PyBUF_MAX_NDIM ограничено максимальное число измерений до 64. Экспортеры должны соблюдать это ограничение, потребители многомерных буферов должны уметь обрабатывать до PyBUF_MAX_NDIM измерений.

Py_ssize_t *shape

Массив из Py_ssize_t длины ndim, указывающий форму памяти как n-мерного массива. Обратите внимание, что shape[0] * ... * shape[ndim-1] * itemsize ДОЛЖЕН быть равен len.

Значения формы ограничены shape[n] >= 0. Случай shape[n] == 0 требует особого внимания. См. сложные массивы для получения дополнительной информации.

Массив формы является только для чтения для потребителя.

Py_ssize_t *strides

Массив из Py_ssize_t длины ndim, задающий количество байтов, которые нужно пропустить, чтобы получить новый элемент в каждом измерении.

Значения шагов могут быть любыми целыми числами. Для обычных массивов шаги обычно положительные, но потребитель ДОЛЖЕН уметь обрабатывать случай strides[n] <= 0. См. сложные массивы для получения дополнительной информации.

Массив шагов является только для чтения для потребителя.

Py_ssize_t *suboffsets

Массив из Py_ssize_t длины ndim. Если suboffsets[n] >= 0, значения, хранящиеся вдоль n-го измерения, являются указателями, и значение смещения определяет, сколько байтов нужно добавить к каждому указателю после разыменования. Значение отрицательного смещения указывает, что разыменование не должно выполняться (шаги по смежному блоку памяти).

Если все смещения отрицательные (т.е. разыменования не требуются), то это поле должно быть NULL (значение по умолчанию).

Этот тип представления массива используется библиотекой Python Imaging Library (PIL). См. сложные массивы для получения дополнительной информации о доступе к элементам такого массива.

Массив смещений является только для чтения для потребителя.

void *internal

Используется внутренне экспортирующим объектом. Например, это может быть переинтерпретировано как целое число экспортером и использовано для хранения флагов о том, нужно ли освобождать массивы shape, strides и suboffsets при освобождении буфера. Потребитель НЕ должен изменять это значение.

Типы запросов на буферы

Буферы обычно получаются путем отправки запроса на буфер объекту-экспортеру через PyObject_GetBuffer(). Поскольку сложность логической структуры памяти может сильно варьироваться, потребитель использует аргумент flags для указания точного типа буфера, который он может обработать.

Все поля Py_buffer однозначно определяются типом запроса.

Сложные массивы

ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1];
item = *((typeof(item) *)ptr);

def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Verify that the parameters represent a valid array within
       the bounds of the allocated memory:
           char *mem: start of the physical memory block
           memlen: length of the physical memory block
           offset: (char *)buf - mem
    """
    if offset % itemsize:
        return False
    if offset < 0 or offset+itemsize > memlen:
        return False
    if any(v % itemsize for v in strides):
        return False

    if ndim <= 0:
        return ndim == 0 and not shape and not strides
    if 0 in shape:
        return True

    imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] <= 0)
    imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
               if strides[j] > 0)

    return 0 <= offset+imin and offset+imax+itemsize <= memlen

void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
                       Py_ssize_t *suboffsets, Py_ssize_t *indices) {
    char *pointer = (char*)buf;
    int i;
    for (i = 0; i < ndim; i++) {
        pointer += strides[i] * indices[i];
        if (suboffsets[i] >=0 ) {
            pointer = *((char**)pointer) + suboffsets[i];
        }
    }
    return (void*)pointer;
}

Функции, связанные с буферами

int PyObject_CheckBuffer(PyObject *obj)

Возвращает 1 если obj поддерживает интерфейс буфера, в противном случае 0. Когда возвращается 1, это не гарантирует, что PyObject_GetBuffer() будет успешным. Данная функция всегда успешна.

int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)

Отправляет запрос exporter для заполнения view в соответствии со спецификацией flags. Если exporter не может предоставить буфер нужного типа, он ДОЛЖЕН вызвать исключение PyExc_BufferError, установить view->obj в NULL и вернуть -1.

В случае успеха, заполняет view, устанавливает view->obj на новую ссылку на exporter и возвращает 0. В случае цепочки поставщиков буферов, которые перенаправляют запросы на один объект, view->obj МОЖЕТ ссылаться на этот объект вместо exporter (См. Структуры объектов буфера).

Успешные вызовы PyObject_GetBuffer() должны быть сопряжены с вызовами PyBuffer_Release(), аналогично malloc() и free(). Таким образом, после того, как потребитель закончил работу с буфером, PyBuffer_Release() должен быть вызван ровно один раз.

void PyBuffer_Release(Py_buffer *view)

Освобождает буфер view и уменьшает счетчик ссылок для view->obj. Данная функция ДОЛЖНА вызываться, когда буфер больше не используется, иначе могут возникнуть утечки памяти.

Ошибка возникает при вызове этой функции для буфера, который не был получен с помощью PyObject_GetBuffer().

Py_ssize_t PyBuffer_SizeFromFormat(const char *)

Возвращает предполагаемое значение itemsize из format. Эта функция пока не реализована.

int PyBuffer_IsContiguous(Py_buffer *view, char order)

Возвращает 1 если память, определённая view, является C-стилевой (order равен 'C') или Fortran-стилевой (order равен 'F') смежной или любой из них (order равен 'A'). В противном случае возвращает 0. Данная функция всегда успешна.

void* PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices)

Получает область памяти, на которую указывают indices внутри данного view. indices должны указывать на массив из view->ndim индексов.

int PyBuffer_FromContiguous(Py_buffer *view, void *buf, Py_ssize_t len, char fort)

Копирует смежные len байт из buf в view. fort может быть 'C' или 'F' (для C-стилевой или Fortran-стилевой упорядоченности). Возвращает 0 при успехе, -1 при ошибке.

int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)

Копирует len байт из src в его смежную форму в buf. order может быть 'C' или 'F' или 'A' (для C-стилевой или Fortran-стилевой упорядоченности или любой из них). Возвращает 0 при успехе, -1 при ошибке.

Функция завершается ошибкой, если len != src->len.

void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)

Заполняет массив strides шагами байтов для смежного (C-стилевого, если order равен 'C' или Fortran-стилевого, если order равен 'F') массива заданной формы с заданным количеством байт на элемент.

int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)

Обрабатывает запросы на буфер для экспортера, который хочет экспонировать buf размером len с записью, установленной в соответствии с readonly. buf интерпретируется как последовательность беззнаковых байт.

Аргумент flags указывает тип запроса. Данная функция всегда заполняет view в соответствии с flags, если buf не был обозначен как только для чтения, а PyBUF_WRITABLE задано в flags.

При успехе установить view->obj на новую ссылку на exporter и вернуть 0. В противном случае вызвать PyExc_BufferError, установить view->obj в NULL и вернуть -1;

Если эта функция используется в рамках getbufferproc, exporter ДОЛЖЕН быть установлен на экспортируемый объект, а flags должны быть переданы без изменений. В противном случае, exporter ДОЛЖЕН быть NULL.