버퍼 프로토콜¶

버퍼 구조체¶

버퍼 구조체(또는 단순히 “버퍼”)는 다른 객체의 바이너리 데이터를 파이썬 프로그래머에게 노출하는 방법으로 유용합니다. 또한, 복사 없는(zero-copy) 슬라이싱 메커니즘으로 사용할 수 있습니다. 메모리 블록을 참조하는 능력을 사용해서, 임의의 데이터를 파이썬 프로그래머에게 아주 쉽게 노출할 수 있습니다. 메모리는 C 확장의 큰 상수 배열일 수 있으며, 운영 체제 라이브러리로 전달되기 전에 조작하기 위한 원시 메모리 블록일 수도 있고, 네이티브 인 메모리(in-memory) 형식으로 구조화된 데이터를 전달하는 데 사용될 수도 있습니다.

파이썬 인터프리터가 노출하는 대부분의 데이터형과 달리, 버퍼는 PyObject 포인터가 아니라 단순한 C 구조체입니다. 이를 통해 매우 간단하게 만들고 복사할 수 있습니다. 버퍼를 감싸는 일반 래퍼가 필요할 때는, 메모리 ë·° 객체를 만들 수 있습니다.

제공하는(exporting) 객체를 작성하는 간단한 지침은 버퍼 객체 구조체를 참조하십시오. 버퍼를 얻으려면, PyObject_GetBuffer()를 참조하십시오.

type Py_buffer¶

Part of the 안정 ABI (including all members) 버전 3.11 이후로.

void *buf¶

버퍼 필드에 의해 기술된 논리적 구조의 시작을 가리키는 포인터. 이것은 제공자(exporter)의 하부 물리적 메모리 블록 내의 모든 위치일 수 있습니다. 예를 들어, 음의 strides를 사용하면 값이 메모리 블록의 끝을 가리킬 수 있습니다.

연속 배열의 경우, 값은 메모리 블록의 시작을 가리킵니다.

PyObject *obj¶

제공하는(exporting) 객체에 대한 새 참조. 참조는 소비자가 소유하고, PyBuffer_Release()에 의해 자동으로 해제되고 (즉 참조 횟수가 감소합니다) NULL로 설정됩니다. 이 필드는 표준 C-API 함수의 반환 값과 동등합니다.

특수한 경우로, PyMemoryView_FromBuffer() 나 PyBuffer_FillInfo()로 감싸진 임시(temporary) 버퍼의 경우, 이 필드는 NULL입니다. 일반적으로, 제공하는(exporting) 객체는 이 체계를 사용하지 않아야 합니다.

Py_ssize_t len¶

product(shape) * itemsize. 연속 배열의 경우, 하부 메모리 블록의 길이입니다. 불연속 배열의 경우, 연속 표현으로 복사된다면 논리적 구조체가 갖게 될 길이입니다.

((char *)buf)[0] 에서 ((char *)buf)[len-1] 범위의 액세스는 연속성을 보장하는 요청으로 버퍼가 확보된 경우에만 유효합니다. 대부분 이러한 요청은 PyBUF_SIMPLE 또는 PyBUF_WRITABLE입니다.

int readonly¶

버퍼가 읽기 전용인지를 나타내는 표시기입니다. 이 필드는 PyBUF_WRITABLE 플래그로 제어됩니다.

Py_ssize_t itemsize¶

단일 요소의 항목 크기(바이트)입니다. NULL이 아닌 format 값에 호출된 struct.calcsize() 값과 같습니다.

중요한 예외: 소비자가 PyBUF_FORMAT 플래그 없이 버퍼를 요청하면, format은 NULL로 설정되지만, itemsize는 여전히 원래 형식의 값을 갖습니다.

shape이 있으면, product(shape) * itemsize == len 동치가 계속 성립하고 소비자는 itemsize를 사용하여 버퍼를 탐색할 수 있습니다.

PyBUF_SIMPLE 이나 PyBUF_WRITABLE 요청의 결과로 shape이 NULL이면, 소비자는 itemsize를 무시하고 itemsize == 1로 가정해야 합니다.

char *format¶

단일 항목의 내용을 설명하는 struct 모듈 스타일 문법의 NULL 종료 문자열. 이것이 NULL이면, "B"(부호 없는 바이트)를 가정합니다.

이 필드는 PyBUF_FORMAT 플래그로 제어됩니다.

int ndim¶

메모리가 n 차원 배열로 나타내는 차원 수. 0이면, buf는 스칼라를 나타내는 단일 항목을 가리 킵니다. 이 경우, shape, strides 및 suboffsets는 반드시 NULL 이어야 합니다. 최대 차원 수는 PyBUF_MAX_NDIM으로 지정됩니다.

Py_ssize_t *shape¶

n-차원 배열로 메모리의 모양을 나타내는 길이 ndim의 Py_ssize_t 배열. shape[0] * ... * shape[ndim-1] * itemsize는 lenê³¼ 같아야 합니다.

모양 값은 shape[n] >= 0로 제한됩니다. shape[n] == 0인 경우는 특별한 주의가 필요합니다. 자세한 정보는 복잡한 배열을 참조하십시오.

shape 배열은 소비자에게 읽기 전용입니다.

Py_ssize_t *strides¶

각 차원에서 새 요소를 가져오기 위해 건너뛸 바이트 수를 제공하는 길이 ndim의 Py_ssize_t 배열.

스트라이드 값은 임의의 정수일 수 있습니다. 일반 배열의 경우, 스트라이드는 보통 양수이지만, 소비자는 strides[n] <= 0인 경우를 처리할 수 있어야 합니다. 자세한 내용은 복잡한 배열을 참조하십시오.

strides 배열은 소비자에게 읽기 전용입니다.

Py_ssize_t *suboffsets¶

길이 ndim의 Py_ssize_t 배열. suboffsets[n] >= 0 ë©´, n 번째 차원을 따라 저장된 값은 포인터이고 서브 오프셋 값은 역참조(de-referencing) 후 각 포인터에 더할 바이트 수를 나타냅니다. 음의 서브 오프셋 값은 역참조(de-referencing)가 발생하지 않아야 함을 나타냅니다 (연속 메모리 블록에서의 스트라이드).

모든 서브 오프셋이 음수면 (즉, 역참조가 필요하지 않으면), 이 필드는 NULL(기본값) 이어야 합니다.

이 유형의 배열 표현은 파이썬 이미징 라이브러리(PIL)에서 사용됩니다. 이러한 배열 요소에 액세스하는 방법에 대한 자세한 내용은 복잡한 배열을 참조하십시오.

suboffsets 배열은 소비자에게 읽기 전용입니다.

void *internal¶

이것은 제공하는(exporting) 객체에 의해 내부적으로 사용됩니다. 예를 들어, 이것은 제공자(exporter)가 정수로 다시 캐스팅할 수 있으며, 버퍼가 해제될 때 shape, strides 및 suboffsets 배열을 해제해야 하는지에 대한 플래그를 저장하는 데 사용됩니다. 소비자가 이 값을 변경해서는 안 됩니다.

상수:

PyBUF_MAX_NDIM¶

Part of the 안정 ABI 버전 3.11 이후로.

메모리가 나타내는 최대 차원 수 입니다. 제공자는 이 제한을 존중해야 하며, 다차원 버퍼의 소비자는 PyBUF_MAX_NDIM 차원까지 처리할 수 있어야 합니다. 현재 64로 설정되었습니다.

버퍼 요청 유형¶

버퍼는 대개 PyObject_GetBuffer()를 통해 제공하는(exporting) 객체로 버퍼 요청을 보내서 얻습니다. 메모리의 논리적 구조의 복잡성이 크게 다를 수 있으므로, 소비자는 처리할 수 있는 정확한 버퍼 유형을 지정하기 위해 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):
    """매개 변수가 할당된 메모리 범위 내에서 유효한 배열을 나타내는지 확인합니다:
           char *mem: 물리적 메모리 블록의 시작
           memlen: 물리적 메모리 블록의 길이
           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)¶

Part of the 안정 ABI 버전 3.11 이후로.

obj가 버퍼 인터페이스를 지원하면 1을 반환하고, 그렇지 않으면 0을 반환합니다. 1이 반환될 때, PyObject_GetBuffer()가 성공할 것이라고 보장하지는 않습니다. 이 함수는 항상 성공합니다.

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

Part of the 안정 ABI 버전 3.11 이후로.

flags에 지정된 대로 view를 채우도록 exporter에게 요청을 보냅니다. 제공자(exporter)가 정확한 유형의 버퍼를 제공할 수 없다면, BufferError를 일으키고, view->obj를 NULL로 설정하고, -1를 반환해야 합니다.

성공하면, view를 채우고, view->obj를 exporter에 대한 새 참조로 설정하고, 0을 반환합니다. 요청을 단일 객체로 리디렉션하는 연결된(chained) 버퍼 공급자의 경우, view->obj는 exporter 대신 이 객체를 참조할 수 있습니다 (버퍼 객체 구조체를 보세요).

PyObject_GetBuffer()에 대한 성공적인 호출은 PyBuffer_Release()에 대한 호출과 쌍을 이루어야 합니다, malloc()ê³¼ free()와 유사합니다. 따라서, 소비자가 버퍼로 작업한 후에는, PyBuffer_Release()를 정확히 한 번 호출해야 합니다.

void PyBuffer_Release(Py_buffer *view)¶

Part of the 안정 ABI 버전 3.11 이후로.

버퍼 view를 해제하고 뷰의 지원 객체인 view->obj에 대한 강한 참조를 해제합니다 (즉 참조 횟수를 감소시킵니다). 버퍼가 더는 사용되지 않을 때, 이 함수를 반드시 호출해야 합니다. 그렇지 않으면 참조 누수가 발생할 수 있습니다.

PyObject_GetBuffer()를 통해 얻지 않은 버퍼에 이 함수를 호출하는 것은 에러입니다.

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)¶

Part of the 안정 ABI 버전 3.11 이후로.

format이 암시하는 itemsize를 반환합니다. 에러가 발생하면, 예외를 발생시키고 -1을 반환합니다.

Added in version 3.9.

int PyBuffer_IsContiguous(const Py_buffer *view, char order)¶

Part of the 안정 ABI 버전 3.11 이후로.

view로 정의된 메모리가 C 스타일(order가 'C')이나 포트란 스타일(order가 'F') 연속이거나 둘 중 하나(order가 'A')ë©´ 1을 반환합니다. 그렇지 않으면 0을 반환합니다. 이 함수는 항상 성공합니다.

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

Part of the 안정 ABI 버전 3.11 이후로.

주어진 view 내부의 indices가 가리키는 메모리 영역을 가져옵니다. indices는 view->ndim 인덱스의 배열을 가리켜야 합니다.

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

Part of the 안정 ABI 버전 3.11 이후로.

buf에 있는 연속된 len 바이트를 view로 복사합니다. fort는 'C' 또는 'F'(C 스타일 또는 포트란 스타일 순서)일 수 있습니다. 성공하면 0이 반환되고, 에러가 있으면 -1이 반환됩니다.

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

Part of the 안정 ABI 버전 3.11 이후로.

src에 있는 len 바이트를 buf에 연속 표현으로 복사합니다. order는 'C' 또는 'F' 또는 'A'(C 스타일 또는 포트란 스타일 순서 또는 둘 중 하나)일 수 있습니다. 성공하면 0이 반환되고, 에러가 있으면 -1이 반환됩니다.

이 함수는 len != src->len이면 실패합니다.

int PyObject_CopyData(PyObject *dest, PyObject *src)¶

Part of the 안정 ABI 버전 3.11 이후로.

Copy data from src to dest buffer. Can convert between C-style and or Fortran-style buffers.

0 is returned on success, -1 on error.

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

Part of the 안정 ABI 버전 3.11 이후로.

strides 배열을 주어진 요소당 바이트 수와 주어진 shape 으로 연속 (order가 'C'ë©´ C 스타일, order가 'F'ë©´ 포트란 스타일) 배열의 바이트 스트라이드로 채웁니다.

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

Part of the 안정 ABI 버전 3.11 이후로.

readonly에 따라 쓰기 가능성이 설정된 len 크기의 buf를 노출하려는 제공자(exporter)에 대한 버퍼 요청을 처리합니다. buf는 부호 없는 바이트의 시퀀스로 해석됩니다.

flags 인자는 요청 유형을 나타냅니다. 이 함수는 buf가 읽기 전용으로 지정되고 PyBUF_WRITABLE이 flags에 설정되어 있지 않으면, 항상 플래그가 지정하는 대로 view를 채웁니다.

성공하면, view->obj를 exporter에 대한 새 참조로 설정하고, 0을 반환합니다. 그렇지 않으면, BufferError를 일으키고, view->obj를 NULL로 설정한 다음 -1을 반환합니다.

이 함수가 getbufferproc의 일부로 사용되면, exporter가 제공하는(exporting) 객체로 설정되어야 하고, flags는 수정되지 않은 채로 전달되어야 합니다. 그렇지 않으면 exporter가 NULL이어야 합니다.