اشیاء متغیرهای زمینه

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

تغییر یافته در نسخه‌ی 3.7.1:

توجه

در پایتون 3.7.1، امضاهای تمام APIهای C مربوط به متغیرهای زمینه تغییر یافتند تا از اشاره‌گرهای PyObject به‌جای PyContext، PyContextVar و PyContextToken استفاده کنند، مثلاً:

// in 3.7.0:
PyContext *PyContext_New(void);

// in 3.7.1+:
PyObject *PyContext_New(void);

برای جزئیات بیشتر به bpo-34762 مراجعه کنید.

این بخش API عمومی C را برای ماژول contextvars به تفصیل شرح می‌دهد.

type PyContext

ساختار C که برای بازنمایی یک شیء contextvars.Context استفاده می‌شود.

type PyContextVar

ساختار C که برای نمایش یک شیء contextvars.ContextVar استفاده می‌شود.

type PyContextToken

ساختار C که برای نمایش یک شیء contextvars.Token استفاده می‌شود.

PyTypeObject PyContext_Type

شیء نوعی که نوع زمینه را نشان می‌دهد.

PyTypeObject PyContextVar_Type

شیء نوعی که نوع متغیر زمینه را نشان می‌دهد.

PyTypeObject PyContextToken_Type

شیء نوعی که نوع توکن متغیر زمینه را نشان می‌دهد.

ماکروهای بررسی نوع:

int PyContext_CheckExact(PyObject *o)

اگر o از نوع PyContext_Type باشد، مقدار true را برمی‌گرداند. o نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyContextVar_CheckExact(PyObject *o)

اگر o از نوع PyContextVar_Type باشد، مقدار true را برمی‌گرداند. o نباید NULL باشد. این تابع همیشه با موفقیت اجرا می‌شود.

int PyContextToken_CheckExact(PyObject *o)

اگر o از نوع PyContextToken_Type باشد، مقدار true را برمی‌گرداند. o نباید NULL باشد. این تابع همیشه موفق می‌شود.

توابع مدیریت شیء زمینه:

PyObject *PyContext_New(void)

مقدار بازگشتی: مرجع جدید.

یک شیء زمینه‌ی خالی جدید ایجاد می‌کند. اگر خطایی رخ داده باشد، NULL را برمی‌گرداند.

PyObject *PyContext_Copy(PyObject *ctx)

مقدار بازگشتی: مرجع جدید.

یک کپی سطحی از شیء زمینه‌ی ctx ارسال‌شده ایجاد می‌کند. اگر خطایی رخ داده باشد، NULL برمی‌گرداند.

PyObject *PyContext_CopyCurrent(void)

مقدار بازگشتی: مرجع جدید.

یک کپی سطحی از زمینه نخ فعلی ایجاد می‌کند. اگر خطایی رخ داده باشد، NULL را برمی‌گرداند.

int PyContext_Enter(PyObject *ctx)

ctx را به‌عنوان زمینه جاری برای نخ جاری تنظیم می‌کند. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

int PyContext_Exit(PyObject *ctx)

زمینه‌ی ctx را غیرفعال می‌کند و زمینه‌ی قبلی را به‌عنوان زمینه‌ی جاری برای نخ جاری بازگردانی می‌کند. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

int PyContext_AddWatcher(PyContext_WatchCallback callback)

callback را به‌عنوان دیده‌بان شیء زمینه برای مفسر فعلی ثبت می‌کند. شناسه‌ای برمی‌گرداند که می‌توان آن را به PyContext_ClearWatcher() پاس داد. در صورت خطا (برای مثال، وقتی دیگر شناسه‌ی دیده‌بانی در دسترس نیست)، مقدار -1 برمی‌گرداند و یک استثنا تنظیم می‌کند.

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

int PyContext_ClearWatcher(int watcher_id)

دیده‌بان شناسایی‌شده با watcher_id که پیش‌تر از PyContext_AddWatcher() برگردانده شده است را برای مفسر جاری حذف می‌کند. در صورت موفقیت 0 را برمی‌گرداند، یا در صورت خطا -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند (برای مثال، اگر watcher_id داده‌شده هرگز ثبت نشده باشد.)

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

type PyContextEvent

شمارش رویدادهای ممکن دیده‌بان (watcher) شیء زمینه:

• Py_CONTEXT_SWITCHED: current context به زمینه‌ای متفاوت تغییر کرده است. شیء پاس‌داده‌شده به کال‌بک نظارت، شیء contextvars.Context است که اکنون فعلی است، یا در صورتی که هیچ زمینه‌ای فعلی نباشد، None است.

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

typedef int (*PyContext_WatchCallback)(PyContextEvent event, PyObject *obj)

تابع کال‌بک ناظر شیء زمینه. شیء پاس‌داده‌شده به کال‌بک مختص رویداد است؛ برای جزئیات به PyContextEvent مراجعه کنید.

اگر کال‌بک همراه با استثنای تنظیم‌شده بازگردد، باید -1 را برگرداند؛ این استثنا با استفاده از PyErr_FormatUnraisable() به‌عنوان یک استثنای غیرقابل‌پرتاب (unraisable exception) چاپ خواهد شد. در غیر این صورت، باید 0 را برگرداند.

ممکن است در هنگام ورود به کال‌بک، از قبل یک استثنای در انتظار تنظیم شده باشد. در این حالت، کال‌بک باید 0 را همراه با همان استثنای همچنان تنظیم‌شده برگرداند. این بدان معناست که کال‌بک نباید هیچ API دیگری را که می‌تواند استثنا تنظیم کند فراخوانی کند، مگر آنکه ابتدا وضعیت استثنا را ذخیره و پاک کند و پیش از بازگشت، آن را بازیابی کند.

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

توابع متغیر زمینه:

PyObject *PyContextVar_New(const char *name, PyObject *def)

مقدار بازگشتی: مرجع جدید.

یک شیء ContextVar جدید ایجاد می‌کند. پارامتر name برای اهداف درون‌نگری و اشکال‌زدایی استفاده می‌شود. پارامتر def یک مقدار پیش‌فرض برای متغیر زمینه مشخص می‌کند، یا NULL در صورت نبود مقدار پیش‌فرض. اگر خطایی رخ داده باشد، این تابع NULL برمی‌گرداند.

int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)

گرفتن مقدار یک متغیر زمینه. اگر در حین جستجو خطایی رخ داده باشد، -1 و اگر خطایی رخ نداده باشد، 0 برمی‌گرداند؛ صرف‌نظر از اینکه مقداری یافت شده است یا نه.

اگر متغیر زمینه یافته شود، value اشاره‌گری به آن خواهد بود. اگر متغیر زمینه یافته نشود، value به موارد زیر اشاره خواهد کرد:

• default_value، اگر NULL نباشد؛

• مقدار پیش‌فرض var، اگر NULL نباشد؛

• NULL

به‌جز NULL، تابع یک ارجاع جدید برمی‌گرداند.

PyObject *PyContextVar_Set(PyObject *var, PyObject *value)

مقدار بازگشتی: مرجع جدید.

مقدار var را در زمینه‌ی فعلی به value تنظیم می‌کند. یک شیء توکن جدید برای این تغییر برمی‌گرداند، یا در صورت وقوع خطا NULL.

int PyContextVar_Reset(PyObject *var, PyObject *token)

وضعیت متغیر زمینه var را به وضعیت پیش از فراخوانی PyContextVar_Set() (که token را برگردانده بود) بازنشانی می‌کند. این تابع در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.