Протокол буфера¶Buffer Protocol

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

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

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

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

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

void *internal¶

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

Типы запросов буфера¶Buffer request types

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

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

Комплексные массивы¶Complex arrays

def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
    """Проверить, что параметры представляют допустимый массив в пределах
       границ выделенной памяти:
           char *mem: начало физического блока памяти
           memlen: длина физического блока памяти
           смещение: (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;
}

Функции, связанные с буфером¶Buffer-related functions

int PyObject_CheckBuffer(PyObject *obj)¶

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

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

Отправить запрос экспортёру на заполнение представления в соответствии с флагами. Если экспортёр не может предоставить буфер нужного типа, он ОБЯЗАН возбудить исключение 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_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)¶

Заполняет массив strides шагами в байтах (byte-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 в соответствии с флагами, за исключением случаев, когда buf помечен как доступный только для чтения и в flags установлен PyBUF_WRITABLE.

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

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