مقداردهی اولیه‌ی چندمرحله‌ای¶

افزونه‌هایی که از مقداردهی اولیه چندمرحله‌ای (تابعونی مانند PyModuleDef_Init()، قلاب اکسپورت PyModExport_*، و PyModule_FromSlotsAndSpec()) استفاده می‌کنند، باید یک Py_mod_gil جایگاه در تعریف ماژول اضافه کنند. اگر افزونه‌ی شما از نسخه‌های قدیمی‌تر سی‌پایتون پشتیبانی می‌کند، باید این جایگاه را با یک بررسی PY_VERSION_HEX محافظت کنید.

static struct PyModuleDef_Slot module_slots[] = {
    ...
#if PY_VERSION_HEX >= 0x030D0000
    {Py_mod_gil, Py_MOD_GIL_NOT_USED},
#endif
    {0, NULL}
};

مقداردهی اولیه‌ی تک‌مرحله‌ای¶

افزونه‌هایی که از مقداردهی اولیه تک‌مرحله‌ای قدیمی (یعنی PyModule_Create()) استفاده می‌کنند، باید PyUnstable_Module_SetGIL() را فراخوانی کنند تا نشان دهند از اجرا با غیرفعال بودن GIL پشتیبانی می‌کنند. این تابع فقط در ساخت نخ‌آزاد تعریف شده است، بنابراین باید فراخوانی را با #ifdef Py_GIL_DISABLED محافظت کنید تا از خطاهای کامپایل در ساخت معمولی جلوگیری شود.

static struct PyModuleDef moduledef = {
    PyModuleDef_HEAD_INIT,
    ...
};

PyMODINIT_FUNC
PyInit_mymodule(void)
{
    PyObject *m = PyModule_Create(&moduledef);
    if (m == NULL) {
        return NULL;
    }
#ifdef Py_GIL_DISABLED
    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);
#endif
    return m;
}

ایمنی نخ در ظرف¶

ظرف‌هایی مانند PyListObject، PyDictObject و PySetObject در ساخت نخ‌آزادقفل‌گذاری داخلی انجام می‌دهند. برای مثال، PyList_Append() پیش از افزودن یک آیتم، فهرست را قفل می‌کند.

Py_BEGIN_CRITICAL_SECTION(dict);
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

بخش‌های بحرانی چیستند؟¶

از نظر مفهومی، بخش‌های بحرانی به‌عنوان لایه‌ای برای اجتناب از بن‌بست عمل می‌کنند که بر روی قفل‌های متقابل ساده (mutex) ساخته شده‌اند. هر نخ، پشته‌ای از بخش‌های بحرانی فعال را نگه می‌دارد. هرگاه نخی نیاز به کسب قفلی مرتبط با یک بخش بحرانی داشته باشد (برای مثال، به‌صورت ضمنی هنگام فراخوانی تابعی ایمن برای نخ از API C مانند PyDict_SetItem()، یا به‌صورت صریح با استفاده از ماکروها)، تلاش می‌کند قفل متقابل زیربنایی را کسب کند.

استفاده از بخش‌های بحرانی¶

APIهای اصلی برای استفاده از بخش‌های بحرانی عبارتند از:

• Py_BEGIN_CRITICAL_SECTION و Py_END_CRITICAL_SECTION - برای قفل‌کردن یک شیء واحد

• Py_BEGIN_CRITICAL_SECTION2 و Py_END_CRITICAL_SECTION2 - برای قفل کردن همزمان دو شیء

این ماکروها باید به‌صورت جفت‌های متناظر استفاده شوند و در یک محدوده C یکسان ظاهر شوند، زیرا آن‌ها یک محدوده محلی جدید ایجاد می‌کنند. این ماکروها در ساخت‌های non-free-threaded بدون عملیات هستند، بنابراین می‌توان آن‌ها را با اطمینان به کدی که نیاز به پشتیبانی از هر دو نوع ساخت دارد، اضافه کرد.

یک استفاده رایج از بخش بحرانی این است که هنگام دسترسی به یک ویژگی داخلی یک شیء، آن شیء را قفل کنید. برای مثال، اگر یک نوع توسعه‌ای دارای یک فیلد شمارش داخلی باشد، می‌توانید هنگام خواندن یا نوشتن آن فیلد از یک بخش بحرانی استفاده کنید:

// خواندن count، یک ارجاع جدید به مقدار داخلی count برمی‌گرداند
PyObject *result;
Py_BEGIN_CRITICAL_SECTION(obj);
result = Py_NewRef(obj->count);
Py_END_CRITICAL_SECTION();
return result;

// نوشتن count، ارجاع new_count را مصرف می‌کند
Py_BEGIN_CRITICAL_SECTION(obj);
obj->count = new_count;
Py_END_CRITICAL_SECTION();

نحوه کار بخش‌های بحرانی¶

برخلاف قفل‌های سنتی، بخش‌های بحرانی دسترسی انحصاری را در تمام مدت خود تضمین نمی‌کنند. اگر نخی در حالی که یک بخش بحرانی را در اختیار دارد مسدود شود (مثلاً با به دست آوردن قفلی دیگر یا انجام I/O)، آن بخش بحرانی به‌طور موقت معلق می‌شود—همه قفل‌ها آزاد می‌شوند—و سپس هنگامی که عملیات مسدودکننده کامل شود، از سر گرفته می‌شود.

این رفتار مشابه اتفاقی است که با GIL هنگامی رخ می‌دهد که یک نخ یک فراخوانی مسدودکننده انجام می‌دهد. تفاوت‌های اصلی عبارتند از:

• بخش‌های بحرانی به‌ازای هر شیء عمل می‌کنند، نه به‌صورت سراسری

• بخش‌های بحرانی در هر نخ از یک نظم پشته‌ای پیروی می‌کنند (ماکروهای «begin» و «end» این موضوع را اعمال می‌کنند، زیرا باید به‌صورت جفت و در یک محدوده یکسان استفاده شوند)

• بخش‌های بحرانی به‌طور خودکار قفل‌ها را پیرامون عملیات‌های مسدودکننده‌ی احتمالی آزاد کرده و دوباره تصاحب می‌کنند

اجتناب از بن‌بست¶

بخش‌های بحرانی به دو روش در جلوگیری از بن‌بست‌ها کمک می‌کنند:

1. اگر یک نخ تلاش کند قفلی را که از قبل در اختیار نخ دیگری است به دست آورد، ابتدا تمام بخش‌های بحرانی فعال خود را معلق می‌کند و قفل‌های آن‌ها را به‌طور موقت آزاد می‌کند

2. هنگامی که عملیات مسدودکننده کامل می‌شود، ابتدا تنها بالاترین بخش بحرانی دوباره به دست می‌آید

این بدان معناست که نمی‌توانید برای قفل کردن چندین شیء به‌طور همزمان، به بخش‌های بحرانی تودرتو اتکا کنید، زیرا بخش بحرانی داخلی ممکن است بخش‌های بحرانی بیرونی را معلق کند. در عوض، برای قفل کردن همزمان دو شیء از Py_BEGIN_CRITICAL_SECTION2 استفاده کنید.

توجه داشته باشید که قفل‌های توصیف‌شده در بالا فقط قفل‌های مبتنی بر PyMutex هستند. پیاده‌سازی بخش بحرانی از سایر سازوکارهای قفل‌سازی که ممکن است در حال استفاده باشند، مانند قفل‌های متقابل POSIX، آگاه نیست و آن‌ها را تحت تأثیر قرار نمی‌دهد. همچنین توجه داشته باشید که هرچند مسدود شدن در انتظار هر PyMutex باعث تعلیق بخش‌های بحرانی می‌شود، فقط قفل‌های متقابلی که بخشی از بخش‌های بحرانی هستند آزاد می‌شوند. اگر PyMutex بدون یک بخش بحرانی استفاده شود، آزاد نخواهد شد و بنابراین از همان اجتناب از بن‌بست بهره‌مند نمی‌شود.

ملاحظات مهم¶

• بخش‌های بحرانی ممکن است قفل‌های خود را به‌طور موقت آزاد کنند و به نخ‌های دیگر اجازه دهند داده‌های محافظت‌شده را تغییر دهند. هنگام فرض‌سازی درباره وضعیت داده‌ها پس از عملیاتی که ممکن است مسدودکننده باشند، احتیاط کنید.

• چون قفل‌ها می‌توانند به‌طور موقت آزاد (معلق) شوند، ورود به یک بخش بحرانی، دسترسی انحصاری به منبع محافظت‌شده را در تمام مدت آن بخش تضمین نمی‌کند. اگر کد درون یک بخش بحرانی تابع دیگری را فراخوانی کند که مسدودکننده است (برای مثال، قفل دیگری را به دست می‌آورد یا ورودی/خروجی مسدودکننده انجام می‌دهد)، تمام قفل‌هایی که نخ از طریق بخش‌های بحرانی در اختیار دارد آزاد خواهند شد. این شبیه به حالتی است که GIL می‌تواند در حین فراخوانی‌های مسدودکننده آزاد شود.

• تنها قفل(ها)ی مرتبط با آخرین بخش بحرانی واردشده (بالاترین) تضمین می‌شود که در هر لحظه نگه‌داشته شده باشند. قفل‌های بخش‌های بحرانی بیرونی و تودرتو ممکن است معلق شده باشند.

• شما می‌توانید با این APIها حداکثر ۲ شیء را به‌طور همزمان قفل کنید. اگر نیاز دارید اشیاء بیشتری را قفل کنید، باید ساختار کد خود را بازآرایی کنید.

• اگرچه بخش‌های بحرانی در صورت تلاش برای قفل کردن دوباره‌ی یک شیء دچار بن‌بست نمی‌شوند، اما برای این مورد استفاده، کارآمدی کمتری نسبت به قفل‌های بازورودپذیر (reentrant locks) دارند که برای همین منظور ساخته شده‌اند.

• هنگام استفاده از Py_BEGIN_CRITICAL_SECTION2، ترتیب شیء‌ها بر صحت تأثیر نمی‌گذارد (پیاده‌سازی اجتناب از بن‌بست را مدیریت می‌کند)، اما بهتر است همیشه شیء‌ها را با ترتیبی ثابت قفل کنید.

• به یاد داشته باشید که ماکروهای بخش بحرانی عمدتاً برای محافظت از دسترسی به اشیای پایتون به کار می‌روند؛ این اشیاء ممکن است در عملیات داخلی CPython که مستعد سناریوهای بن‌بست توصیف‌شده در بالا هستند، دخیل باشند. برای محافظت از وضعیت کاملاً داخلی افزونه، ممکن است قفل‌های متقابل استاندارد یا دیگر سازوکارهای همگام‌سازی مناسب‌تر باشند.

قفل‌های مخصوص هر شیء (ob_mutex)¶

در ساخت نخ‌آزاد، هر شیء پایتون شامل یک فیلد ob_mutex از نوع PyMutex است. این قفل متقابل برای استفاده توسط API بخش بحرانی (Py_BEGIN_CRITICAL_SECTION / Py_END_CRITICAL_SECTION) رزرو شده است.

حتی اگر کد خودتان هرگز از بخش‌های بحرانی روی یک نوع شیء خاص استفاده نکند، بخش‌های داخلی سی‌پایتون ممکن است از API بخش بحرانی روی هر شیء پایتونی استفاده کنند.

اگر نوع افزونه‌ی شما به قفل خودش نیاز دارد، یک فیلد مجزای PyMutex (یا یک اولیه‌ی همگام‌سازی دیگر) به ساختار شیء خود اضافه کنید. PyMutex بسیار سبک است، بنابراین داشتن یک قفل اضافی هزینه‌ی ناچیزی دارد.

API محدود C و ABI پایدار¶

ساخت نخ‌آزادی (free-threaded build) در حال حاضر از Limited C API یا ABI پایدار پشتیبانی نمی‌کند. اگر برای ساخت افزونه خود از setuptools استفاده می‌کنید و در حال حاضر py_limited_api=True را تنظیم کرده‌اید، می‌توانید برای خارج شدن از API محدود هنگام ساخت با ساخت نخ‌آزادی، از py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED") استفاده کنید.

ویندوز¶

به دلیل محدودیتی در نصب‌کننده رسمی ویندوز، هنگام ساخت افزونه‌ها از منبع، باید به‌صورت دستی Py_GIL_DISABLED=1 را تعریف کنید.