ساختار بافر¶

ساختارهای بافر (یا به‌سادگی «بافرها») به‌عنوان راهی برای افشای داده‌های دودویی از یک شیء دیگر به برنامه‌نویس پایتون مفید هستند. همچنین می‌توان از آن‌ها به‌عنوان سازوکاری برای اسلایس‌کردن بدون کپی استفاده کرد. با استفاده از توانایی آن‌ها در ارجاع به یک بلوک حافظه، می‌توان هر داده‌ای را به‌سادگی به برنامه‌نویس پایتون افشا کرد. این حافظه می‌تواند یک آرایه‌ی بزرگ و ثابت در یک توسعه C باشد، می‌تواند یک بلوک خام حافظه برای دستکاری پیش از انتقال به یک کتابخانه‌ی سیستم‌عامل باشد، یا می‌تواند برای به‌گردش درآوردن داده‌های ساختاریافته در قالب بومی و درون‌حافظه‌ای خود استفاده شود.

برخلاف بیشتر نوع‌های داده‌ای که مفسر پایتون ارائه می‌کند، بافرها اشاره‌گرهای PyObject نیستند، بلکه ساختارهای ساده‌ی C هستند. این امر امکان می‌دهد که آن‌ها به‌سادگی ساخته و کپی شوند. وقتی به یک دربرگیرنده‌ی عام برای بافر نیاز باشد، می‌توان یک شیء memoryview ایجاد کرد.

برای دستورالعمل‌های کوتاه درباره‌ی نحوه‌ی نوشتن یک شیء اکسپورتکننده (exporting object)، به ساختارهای شیء بافر مراجعه کنید. برای به دست آوردن یک بافر، به PyObject_GetBuffer() مراجعه کنید.

type Py_buffer¶

قسمتی از ABI پایدار شامل تمام اعضا از نسخه‌ی 3.11.

void *buf¶

اشاره‌گری به ابتدای ساختار منطقی‌ای که توسط فیلدهای بافر توصیف می‌شود. این می‌تواند هر مکانی درون بلوک حافظه فیزیکی زیرین اکسپورتکننده باشد. برای مثال، با strides منفی، مقدار ممکن است به انتهای بلوک حافظه اشاره کند.

برای آرایه‌های پیوسته، مقدار به ابتدای بلوک حافظه اشاره می‌کند.

PyObject *obj¶

ارجاعی جدید به شیء اکسپورتکننده. این ارجاع در مالکیت مصرف‌کننده است و به‌طور خودکار توسط PyBuffer_Release() آزاد می‌شود (یعنی شمارش ارجاع کاهش می‌یابد) و به NULL تنظیم می‌شود. این فیلد معادل مقدار بازگشتی هر تابع استاندارد 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 برابر NULL باشد، مصرف‌کننده باید itemsize را نادیده بگیرد و فرض کند که itemsize == 1 است.

char *format¶

رشته‌ای خاتمه‌یافته با NULL به سبک سینتکس ماژول struct که محتویات یک آیتم منفرد را توصیف می‌کند. اگر این NULL باشد، "B" (بایت‌های بدون علامت) فرض می‌شود.

این فیلد توسط پرچم PyBUF_FORMAT کنترل می‌شود.

int ndim¶

تعداد ابعادی که حافظه به‌صورت یک آرایه‌ی n-بعدی بازنمایی می‌کند. اگر 0 باشد، buf به یک آیتم واحد اشاره می‌کند که نمایانگر یک اسکالر است. در این حالت، shape، strides و suboffsets باید NULL باشند. حداکثر تعداد ابعاد توسط 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 که مشخص می‌کند برای رسیدن به عنصر جدید در هر بُعد باید چند بایت را رد کرد.

مقادیر گام (stride) می‌توانند هر عدد صحیحی باشند. برای آرایه‌های معمولی، گام‌ها معمولاً مثبت هستند، اما مصرف‌کننده باید حتماً بتواند مورد strides[n] <= 0 را مدیریت کند. برای اطلاعات بیشتر به complex arrays مراجعه کنید.

آرایه‌ی strides برای مصرف‌کننده فقط‌خواندنی است.

Py_ssize_t *suboffsets¶

آرایه‌ای از Py_ssize_t به طول ndim. اگر suboffsets[n] >= 0 باشد، مقادیر ذخیره‌شده در راستای بعد n-اُم اشاره‌گر هستند و مقدار زیرآفست تعیین می‌کند که پس از ارجاع‌زدایی (de-referencing)، چند بایت باید به هر اشاره‌گر افزوده شود. مقدار منفیِ زیرآفست نشان می‌دهد که نباید ارجاع‌زدایی انجام شود (گام‌برداری (striding) در یک بلوک حافظه‌ی پیوسته).

اگر همه‌ی suboffsets منفی باشند (یعنی نیازی به ارجاع‌زدایی نیست)، آن‌گاه این فیلد باید NULL باشد (مقدار پیش‌فرض).

این نوع نمایش آرایه توسط Python Imaging Library (PIL) استفاده می‌شود. برای اطلاعات بیشتر درباره‌ی نحوه‌ی دسترسی به عناصر چنین آرایه‌ای، به complex arrays مراجعه کنید.

آرایه‌ی suboffsets برای مصرف‌کننده فقط‌خواندنی است.

void *internal¶

این مورد برای استفاده داخلی توسط شیء اکسپورتکننده است. برای مثال، اکسپورتکننده ممکن است آن را به یک عدد صحیح قالب‌ریزی مجدد کند و از آن برای ذخیره پرچم‌هایی استفاده کند که مشخص می‌کنند آرایه‌های shape، strides و suboffsets هنگام رها شدن بافر باید آزاد شوند یا خیر. مصرف‌کننده به هیچ وجه نباید این مقدار را تغییر دهد.

ثابت‌ها:

PyBUF_MAX_NDIM¶

قسمتی از ABI پایدار از نسخه‌ی 3.11.

حداکثر تعداد ابعادی که حافظه بازنمایی می‌کند. اکسپورتکنندگان باید (MUST) این محدودیت را رعایت کنند و بهتر است (SHOULD) مصرف‌کنندگان بافرهای چندبعدی بتوانند تا PyBUF_MAX_NDIM بعد را مدیریت کنند. در حال حاضر روی ۶۴ تنظیم شده است.

انواع درخواست بافر¶

بافرها معمولاً با ارسال درخواست بافر به یک شیء اکسپورتکننده از طریق PyObject_GetBuffer() به دست می‌آیند. از آنجا که پیچیدگی ساختار منطقی حافظه می‌تواند به‌شدت متفاوت باشد، مصرف‌کننده از آرگومان پرچم‌ها برای تعیین نوع دقیق بافری که می‌تواند آن را مدیریت کند استفاده می‌کند.

همه‌ی فیلدهای 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)¶

قسمتی از ABI پایدار از نسخه‌ی 3.11.

اگر obj از رابط بافر پشتیبانی کند، 1 و در غیر این صورت 0 را برمی‌گرداند. برگرداندن 1 تضمین نمی‌کند که PyObject_GetBuffer() موفق شود. این تابع همیشه موفق است.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

درخواستی به اکسپورتکننده ارسال می‌شود تا نما را همان‌طور که پرچم‌ها مشخص کرده‌اند، پر کند. اگر اکسپورتکننده نتواند بافری از دقیقاً همان نوع ارائه دهد، باید استثنای 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)¶

قسمتی از ABI پایدار از نسخه‌ی 3.11.

نمای بافر را آزاد می‌کند و ارجاع قوی (یعنی کاهش شمارش ارجاع) به شیء پشتیبان نما، view->obj، را آزاد می‌کند. این تابع باید زمانی که دیگر از بافر استفاده نمی‌شود حتماً فراخوانی شود، در غیر این صورت ممکن است نشت ارجاع رخ دهد.

فراخوانی این تابع روی بافری که از طریق PyObject_GetBuffer() به دست نیامده است، خطا است.

Py_ssize_t PyBuffer_SizeFromFormat(const char *format)¶

قسمتی از ABI پایدار از نسخه‌ی 3.11.

itemsize ضمنی را از format برمی‌گرداند. در صورت خطا، یک استثنا مطرح می‌کند و -1 برمی‌گرداند.

اضافه شده در نسخه‌ی 3.9.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

اگر حافظه‌ی تعریف‌شده توسط view به سبک C (order برابر 'C' است) یا به سبک Fortran (order برابر 'F' است) پیوسته باشد یا هر یک از این دو (order برابر 'A' است)، 1 را برمی‌گرداند. در غیر این صورت 0 برمی‌گرداند. این تابع همیشه موفق می‌شود.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

به دست آوردن ناحیه حافظه‌ای درون view داده‌شده که indices به آن اشاره می‌کند. indices باید به آرایه‌ای از view->ndim اندیس اشاره کند.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

تعداد len بایت پیوسته را از buf به view کپی کنید. پارامتر order می‌تواند 'C'، 'F' یا 'A' باشد (به ترتیب برای ترتیب‌بندی سبک C، سبک فرترن یا هرکدام). در صورت موفقیت 0 و در صورت خطا -1 برگردانده می‌شود.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

len بایت از src را به نمایش پیوسته‌ی آن در buf کپی می‌کند. order می‌تواند 'C' یا 'F' یا 'A' باشد (برای ترتیب به سبک C یا سبک Fortran یا هر یک از این دو). در صورت موفقیت 0 و در صورت خطا -1 برگردانده می‌شود.

این تابع در صورتی که len != src->len باشد شکست می‌خورد.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

داده‌ها را از بافر src به بافر dest کپی می‌کند. می‌تواند بین بافرهای سبک C و یا سبک Fortran تبدیل انجام دهد.

در صورت موفقیت 0 و در صورت خطا -1 برگردانده می‌شود.

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

قسمتی از ABI پایدار از نسخه‌ی 3.11.

آرایه‌ی 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)¶

قسمتی از ABI پایدار از نسخه‌ی 3.11.

درخواست‌های بافر را برای اکسپورتکننده‌ای (exporter) که می‌خواهد buf را با اندازه‌ی len و با قابلیت نوشتنِ تنظیم‌شده بر اساس readonly افشا کند، مدیریت می‌کند. buf به‌عنوان دنباله‌ای از بایت‌های بدون علامت تفسیر می‌شود.

آرگومان flags نوع درخواست را نشان می‌دهد. این تابع همیشه view را مطابق با flags پر می‌کند، مگر آنکه buf به‌عنوان فقط‌خواندنی تعیین‌شده باشد و PyBUF_WRITABLE در flags تنظیم‌شده باشد.

در صورت موفقیت، view->obj را برابر ارجاعی جدید به exporter قرار دهید و 0 را برگردانید. در غیر این صورت، استثنای BufferError را raise کنید، view->obj را برابر NULL قرار دهید و -1 را برگردانید؛

اگر این تابع به عنوان بخشی از getbufferproc استفاده شود، exporter باید برابر با شیء اکسپورتکننده تنظیم شود و flags باید دست‌نخورده ارسال شود. در غیر این صورت، exporter باید NULL باشد.