Протокол буфера¶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¶

Строка, завершающаяся 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 при освобождении буфера. Потребитель НЕ ДОЛЖЕН изменять это значение.

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

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

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

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

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):
    """Проверить, что параметры представляют допустимый массив в пределах
       границ выделенной памяти:
           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)¶

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

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