Буферный протокол¶

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

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

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

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

type Py_buffer¶

void *buf¶

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

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

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 является NULL в результате запроса 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 требует особого внимания. Дополнительную информацию см. в разделе complex arrays.

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

Py_ssize_t *strides¶

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

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

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

Py_ssize_t *suboffsets¶

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

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

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

Массив 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, указанного флагами. Если экспортер не может предоставить буфер точного типа, он ДОЛЖЕН поднять PyExc_BufferError, установить view->obj в NULL и вернуть -1.

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

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

void PyBuffer_Release(Py_buffer *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, как указано флагами, если только buf не был назначен как доступный только для чтения и в flags не установлено PyBUF_WRITABLE.

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

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