Протокол буфера

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

Структуры буферов (или просто «буферы») полезны как способ экспонирования двоичных данных из другого объекта для программиста 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

Строка с нулевым окончанием в формате модуля 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-го измерения, являются указателями, и значение suboffset определяет, сколько байтов нужно добавить к каждому указателю после разыменования. Значение suboffset, которое отрицательно, указывает, что разыменование не должно происходить (шаги по блоку смежной памяти).

Если все suboffset отрицательны (то есть разыменования не требуется), то это поле ДОЛЖНО быть NULL (значение по умолчанию).

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

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

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)

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

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

Успешные вызовы 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 *format)

Возвращает значение itemsize, вычисленное по format. В случае ошибки генерирует исключение и возвращает -1.

Добавлена в версии 3.9.

int PyBuffer_IsContiguous(Py_buffer *view, char order)

Возвращает 1 если память, определенная view, имеет порядок C (order равен 'C') или Fortran (order равен 'F') contiguous, либо любой из них (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 шагами байтов contiguous (порядка 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 на новую ссылку на экспортер и возвращает 0. Иначе, генерирует PyExc_BufferError, устанавливает view->obj в NULL и возвращает -1;

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