free-threading-extensions.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
# Translators:
# Rafael Fontenelle <rffontenelle@gmail.com>, 2025
# Revisto <theRevisto@gmail.com>, 2025
# Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026
# arman mohebali <armanmohebali@outlook.com>, 2026
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-10-01 14:41+0330\n"
"PO-Revision-Date: 2026-09-13 16:17+0330\n"
"Last-Translator: Sepehr Rasouli <sepehrrasouli06@gmail.com>, 2026\n"
"Language-Team: Persian (https://github.com/python/python-docs-fa/)\n"
"Language: fa\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n > 1);\n"
"X-Generator: Poedit 3.6\n"

msgid "C API Extension Support for Free Threading"
msgstr "پشتیبانی افزونه‌های C API از نخ‌بندی آزاد"

msgid "Starting with the 3.13 release, CPython has support for running with the :term:`global interpreter lock` (GIL) disabled in a configuration called :term:`free threading`.  This document describes how to adapt C API extensions to support free threading."
msgstr "از نسخه‌ی 3.13 به بعد، CPython از اجرا در پیکربندی‌ای به نام :term:`قفل مفسر سراسری <global interpreter lock>` پشتیبانی می‌کند که در آن :term:`نخ‌آزاد <free threading>` (GIL) غیرفعال است. این سند نحوه‌ی سازگار کردن افزونه‌های C API برای پشتیبانی از نخ‌آزاد را توضیح می‌دهد."

msgid "Identifying the Free-Threaded Build in C"
msgstr "شناسایی ساخت نخ‌آزادی در C"

msgid "The CPython C API exposes the ``Py_GIL_DISABLED`` macro: in the free-threaded build it's defined to ``1``, and in the regular build it's not defined. You can use it to enable code that only runs under the free-threaded build::"
msgstr "API زبان C در CPython ماکروی ``Py_GIL_DISABLED`` را در معرض قرار می‌دهد: در ساخت نخ‌آزاد (free-threaded build) به مقدار ``1`` تعریف شده است و در ساخت معمولی تعریف نشده است. می‌توانید از آن برای فعال کردن کدی استفاده کنید که فقط در ساخت نخ‌آزاد اجرا می‌شود::"

msgid ""
"#ifdef Py_GIL_DISABLED\n"
"/* code that only runs in the free-threaded build */\n"
"#endif"
msgstr ""
"#ifdef Py_GIL_DISABLED\n"
"/* code that only runs in the free-threaded build */\n"
"#endif"

msgid "On Windows, this macro is not defined automatically, but must be specified to the compiler when building. The :func:`sysconfig.get_config_var` function can be used to determine whether the current running interpreter had the macro defined."
msgstr "در ویندوز، این ماکرو به‌طور خودکار تعریف نمی‌شود، بلکه باید هنگام ساخت به کامپایلر اعلام شود. برای تشخیص این‌که آیا این ماکرو در مفسر در حال اجرای فعلی تعریف شده است یا نه، می‌توانید از تابع :func:`sysconfig.get_config_var` استفاده کنید."

msgid "Module Initialization"
msgstr "مقداردهی اولیه ماژول"

msgid "Extension modules need to explicitly indicate that they support running with the GIL disabled; otherwise importing the extension will raise a warning and enable the GIL at runtime."
msgstr "ماژول‌های توسعه‌ای باید به‌صراحت اعلام کنند که از اجرا با GIL غیرفعال پشتیبانی می‌کنند؛ در غیر این صورت، ایمپورت کردن ماژول توسعه‌ای باعث پرتاب یک هشدار می‌شود و GIL را در ران‌تایم فعال می‌کند."

msgid "There are two ways to indicate that an extension module supports running with the GIL disabled depending on whether the extension uses multi-phase or single-phase initialization."
msgstr "بسته به اینکه یک ماژول توسعه از مقداردهی اولیه‌ی چندمرحله‌ای یا تک‌مرحله‌ای استفاده کند، دو روش برای نشان دادن پشتیبانی آن از اجرا با GIL غیرفعال وجود دارد."

msgid "Multi-Phase Initialization"
msgstr "مقداردهی اولیه‌ی چندمرحله‌ای"

msgid "Extensions that use :ref:`multi-phase initialization <multi-phase-initialization>` (functions like :c:func:`PyModuleDef_Init`, :c:func:`PyModExport_* <PyModExport_modulename>` export hook, :c:func:`PyModule_FromSlotsAndSpec`) should add a :c:data:`Py_mod_gil` slot in the module definition. If your extension supports older versions of CPython, you should guard the slot with a :c:data:`PY_VERSION_HEX` check."
msgstr "افزونه‌هایی که از :ref:`مقداردهی اولیه چندمرحله‌ای <multi-phase-initialization>` (تابعونی مانند :c:func:`PyModuleDef_Init`، قلاب اکسپورت :c:func:`PyModExport_* <PyModExport_modulename>`، و :c:func:`PyModule_FromSlotsAndSpec`) استفاده می‌کنند، باید یک :c:data:`Py_mod_gil` جایگاه در تعریف ماژول اضافه کنند. اگر افزونه‌ی شما از نسخه‌های قدیمی‌تر سی‌پایتون پشتیبانی می‌کند، باید این جایگاه را با یک بررسی :c:data:`PY_VERSION_HEX` محافظت کنید."

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

msgid "Single-Phase Initialization"
msgstr "مقداردهی اولیه‌ی تک‌مرحله‌ای"

msgid "Extensions that use legacy :ref:`single-phase initialization <single-phase-initialization>` (that is, :c:func:`PyModule_Create`) should call :c:func:`PyUnstable_Module_SetGIL` to indicate that they support running with the GIL disabled.  The function is only defined in the free-threaded build, so you should guard the call with ``#ifdef Py_GIL_DISABLED`` to avoid compilation errors in the regular build."
msgstr "افزونه‌هایی که از :ref:`مقداردهی اولیه تک‌مرحله‌ای <single-phase-initialization>` قدیمی (یعنی :c:func:`PyModule_Create`) استفاده می‌کنند، باید :c:func:`PyUnstable_Module_SetGIL` را فراخوانی کنند تا نشان دهند از اجرا با غیرفعال بودن GIL پشتیبانی می‌کنند. این تابع فقط در ساخت نخ‌آزاد تعریف شده است، بنابراین باید فراخوانی را با ``#ifdef Py_GIL_DISABLED`` محافظت کنید تا از خطاهای کامپایل در ساخت معمولی جلوگیری شود."

msgid ""
"static struct PyModuleDef moduledef = {\n"
"    PyModuleDef_HEAD_INIT,\n"
"    ...\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_mymodule(void)\n"
"{\n"
"    PyObject *m = PyModule_Create(&moduledef);\n"
"    if (m == NULL) {\n"
"        return NULL;\n"
"    }\n"
"#ifdef Py_GIL_DISABLED\n"
"    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n"
"#endif\n"
"    return m;\n"
"}"
msgstr ""
"static struct PyModuleDef moduledef = {\n"
"    PyModuleDef_HEAD_INIT,\n"
"    ...\n"
"};\n"
"\n"
"PyMODINIT_FUNC\n"
"PyInit_mymodule(void)\n"
"{\n"
"    PyObject *m = PyModule_Create(&moduledef);\n"
"    if (m == NULL) {\n"
"        return NULL;\n"
"    }\n"
"#ifdef Py_GIL_DISABLED\n"
"    PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);\n"
"#endif\n"
"    return m;\n"
"}"

msgid "General API Guidelines"
msgstr "دستورالعمل‌های کلی API"

msgid "Most of the C API is thread-safe, but there are some exceptions."
msgstr "بیشتر C API نخ‌ایمن است، اما استثناهایی وجود دارد."

msgid "**Struct Fields**: Accessing fields in Python C API objects or structs directly is not thread-safe if the field may be concurrently modified."
msgstr "**فیلدهای ساختار**: دسترسی مستقیم به فیلدها در اشیاء یا ساختارهای Python C API، اگر فیلد ممکن است به‌طور همزمان تغییر کند، نخ‌ایمن نیست."

msgid "**Macros**: Accessor macros like :c:macro:`PyList_GET_ITEM`, :c:macro:`PyList_SET_ITEM`, and macros like :c:macro:`PySequence_Fast_GET_SIZE` that use the object returned by :c:func:`PySequence_Fast` do not perform any error checking or locking. These macros are not thread-safe if the container object may be modified concurrently."
msgstr "**ماکروها**: ماکروهای دسترسی‌گر مانند :c:macro:`PyList_GET_ITEM`، :c:macro:`PyList_SET_ITEM` و ماکروهایی مانند :c:macro:`PySequence_Fast_GET_SIZE` که از شیء برگردانده‌شده توسط :c:func:`PySequence_Fast` استفاده می‌کنند، هیچ‌گونه بررسی خطا یا قفل‌گذاری‌ای انجام نمی‌دهند. این ماکروها نخ‌ایمن (thread-safe) نیستند اگر ممکن باشد شیء نگهدارنده همزمان تغییر داده شود."

msgid "**Borrowed References**: C API functions that return :term:`borrowed references <borrowed reference>` may not be thread-safe if the containing object is modified concurrently.  See the section on :ref:`borrowed references <borrowed-references>` for more information."
msgstr "**ارجاع‌های امانتی**: توابع C API که :term:`ارجاع‌های امانتی <borrowed reference>` را برمی‌گردانند، ممکن است در صورتی که شیء دربردارنده به‌طور همزمان تغییر کند، ایمن در برابر نخ نباشند. برای اطلاعات بیشتر، بخش :ref:`ارجاع‌های امانتی <borrowed-references>` را ببینید."

msgid "Container Thread Safety"
msgstr "ایمنی نخ در ظرف"

msgid "Containers like :c:struct:`PyListObject`, :c:struct:`PyDictObject`, and :c:struct:`PySetObject` perform internal locking in the free-threaded build.  For example, the :c:func:`PyList_Append` will lock the list before appending an item."
msgstr "ظرف‌هایی مانند :c:struct:`PyListObject`، :c:struct:`PyDictObject` و :c:struct:`PySetObject` در ساخت نخ‌آزادقفل‌گذاری داخلی انجام می‌دهند. برای مثال، :c:func:`PyList_Append` پیش از افزودن یک آیتم، فهرست را قفل می‌کند."

msgid "``PyDict_Next``"
msgstr "``PyDict_Next``"

msgid "A notable exception is :c:func:`PyDict_Next`, which does not lock the dictionary.  You should use :c:macro:`Py_BEGIN_CRITICAL_SECTION` to protect the dictionary while iterating over it if the dictionary may be concurrently modified::"
msgstr "یک استثنای قابل‌توجه :c:func:`PyDict_Next` است، که دیکشنری را قفل نمی‌کند. اگر ممکن است دیکشنری به‌صورت همزمان تغییر داده شود، شما باید برای محافظت از دیکشنری در حین پیمایش آن از :c:macro:`Py_BEGIN_CRITICAL_SECTION` استفاده کنید::"

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

msgid "Borrowed References"
msgstr "ارجاع‌های امانتی"

msgid "Some C API functions return :term:`borrowed references <borrowed reference>`. These APIs are not thread-safe if the containing object is modified concurrently.  For example, it's not safe to use :c:func:`PyList_GetItem` if the list may be modified concurrently."
msgstr "برخی از توابع C API، :term:`ارجاع‌های امانتی <borrowed reference>` را بازمی‌گردانند. این APIها در صورتی که شیء حاوی آن‌ها به‌طور همزمان تغییر کند، نخ‌ایمن نیستند. برای مثال، اگر ممکن است فهرست به‌طور همزمان تغییر کند، استفاده از :c:func:`PyList_GetItem` ایمن نیست."

msgid "The following table lists some borrowed reference APIs and their replacements that return :term:`strong references <strong reference>`."
msgstr "جدول زیر برخی APIهای ارجاع امانتی (borrowed reference) و جایگزین‌های آن‌ها را که :term:`ارجاع‌های قوی <strong reference>` را برمی‌گردانند، فهرست می‌کند."

msgid "Borrowed reference API"
msgstr "API ارجاع امانتی"

msgid "Strong reference API"
msgstr "API ارجاع قوی"

msgid ":c:func:`PyList_GetItem`"
msgstr ":c:func:`PyList_GetItem`"

msgid ":c:func:`PyList_GetItemRef`"
msgstr ":c:func:`PyList_GetItemRef`"

msgid ":c:func:`PyList_GET_ITEM`"
msgstr ":c:func:`PyList_GET_ITEM`"

msgid ":c:func:`PyDict_GetItem`"
msgstr ":c:func:`PyDict_GetItem`"

msgid ":c:func:`PyDict_GetItemRef`"
msgstr ":c:func:`PyDict_GetItemRef`"

msgid ":c:func:`PyDict_GetItemWithError`"
msgstr ":c:func:`PyDict_GetItemWithError`"

msgid ":c:func:`PyDict_GetItemString`"
msgstr ":c:func:`PyDict_GetItemString`"

msgid ":c:func:`PyDict_GetItemStringRef`"
msgstr ":c:func:`PyDict_GetItemStringRef`"

msgid ":c:func:`PyDict_SetDefault`"
msgstr ":c:func:`PyDict_SetDefault`"

msgid ":c:func:`PyDict_SetDefaultRef`"
msgstr ":c:func:`PyDict_SetDefaultRef`"

msgid ":c:func:`PyDict_Next`"
msgstr ":c:func:`PyDict_Next`"

msgid "none (see :ref:`PyDict_Next`)"
msgstr "هیچ (به :ref:`PyDict_Next` رجوع کنید)"

msgid ":c:func:`!PyWeakref_GetObject`"
msgstr ":c:func:`!PyWeakref_GetObject`"

msgid ":c:func:`PyWeakref_GetRef`"
msgstr ":c:func:`PyWeakref_GetRef`"

msgid ":c:func:`!PyWeakref_GET_OBJECT`"
msgstr ":c:func:`!PyWeakref_GET_OBJECT`"

msgid ":c:func:`PyImport_AddModule`"
msgstr ":c:func:`PyImport_AddModule`"

msgid ":c:func:`PyImport_AddModuleRef`"
msgstr ":c:func:`PyImport_AddModuleRef`"

msgid ":c:func:`PyCell_GET`"
msgstr ":c:func:`PyCell_GET`"

msgid ":c:func:`PyCell_Get`"
msgstr ":c:func:`PyCell_Get`"

msgid "Not all APIs that return borrowed references are problematic.  For example, :c:func:`PyTuple_GetItem` is safe because tuples are immutable. Similarly, not all uses of the above APIs are problematic.  For example, :c:func:`PyDict_GetItem` is often used for parsing keyword argument dictionaries in function calls; those keyword argument dictionaries are effectively private (not accessible by other threads), so using borrowed references in that context is safe."
msgstr "همه‌ی APIهایی که ارجاع‌های امانتی (borrowed references) را برمی‌گردانند، مشکل‌ساز نیستند. برای مثال، :c:func:`PyTuple_GetItem` ایمن است، زیرا تاپل‌ها تغییرناپذیر هستند. به‌طور مشابه، همه‌ی استفاده‌های APIهای بالا مشکل‌ساز نیستند. برای مثال، :c:func:`PyDict_GetItem` اغلب برای تجزیه‌ی دیکشنری‌های آرگومان کلیدواژه‌ای در فراخوانی‌های تابع استفاده می‌شود؛ آن دیکشنری‌های آرگومان کلیدواژه‌ای عملاً خصوصی هستند (برای نخ‌های دیگر قابل دسترسی نیستند)، بنابراین استفاده از ارجاع‌های امانتی در آن زمینه ایمن است."

msgid "Some of these functions were added in Python 3.13.  You can use the `pythoncapi-compat <https://github.com/python/pythoncapi-compat>`_ package to provide implementations of these functions for older Python versions."
msgstr "برخی از این توابع در پایتون 3.13 افزوده شده‌اند. شما می‌توانید از بسته‌ی `pythoncapi-compat <https://github.com/python/pythoncapi-compat>`_ برای فراهم کردن پیاده‌سازی این توابع برای نسخه‌های قدیمی‌تر پایتون استفاده کنید."

msgid "Memory Allocation APIs"
msgstr "APIهای تخصیص حافظه"

msgid "Python's memory management C API provides functions in three different :ref:`allocation domains <allocator-domains>`: \"raw\", \"mem\", and \"object\". For thread-safety, the free-threaded build requires that only Python objects are allocated using the object domain, and that all Python objects are allocated using that domain.  This differs from the prior Python versions, where this was only a best practice and not a hard requirement."
msgstr "C API مدیریت حافظه‌ی پایتون، توابعی را در سه :ref:`دامنه‌ی تخصیص <allocator-domains>` متفاوت فراهم می‌کند: \"raw\"، \"mem\" و \"object\". برای ایمنی نخ‌ها، ساخت free-threaded ایجاب می‌کند که تنها اشیای پایتون با استفاده از دامنه‌ی object تخصیص داده شوند و همه‌ی اشیای پایتون نیز با استفاده از آن دامنه تخصیص داده شوند. این با نسخه‌های پیشین پایتون تفاوت دارد؛ در آن نسخه‌ها، این فقط یک بهترین روش بود و نه یک الزام سخت."

msgid "Search for uses of :c:func:`PyObject_Malloc` in your extension and check that the allocated memory is used for Python objects. Use :c:func:`PyMem_Malloc` to allocate buffers instead of :c:func:`PyObject_Malloc`."
msgstr "موارد استفاده از :c:func:`PyObject_Malloc` را در افزونه خود جستجو کنید و بررسی کنید که حافظه تخصیص‌یافته برای اشیای پایتون استفاده می‌شود. برای تخصیص بافرها به جای :c:func:`PyObject_Malloc` از :c:func:`PyMem_Malloc` استفاده کنید."

msgid "Thread State and GIL APIs"
msgstr "وضعیت نخ و APIهای GIL"

msgid "Python provides a set of functions and macros to manage thread state and the GIL, such as:"
msgstr "پایتون مجموعه‌ای از توابع و ماکروها را برای مدیریت وضعیت نخ و GIL فراهم می‌کند، مانند:"

msgid ":c:func:`PyThreadState_Ensure`, :c:func:`PyThreadState_EnsureFromView`, and :c:func:`PyThreadState_Release`"
msgstr ":c:func:`PyThreadState_Ensure`، :c:func:`PyThreadState_EnsureFromView` و :c:func:`PyThreadState_Release`"

msgid ":c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`"
msgstr ":c:func:`PyGILState_Ensure` و :c:func:`PyGILState_Release`"

msgid ":c:func:`PyEval_SaveThread` and :c:func:`PyEval_RestoreThread`"
msgstr ":c:func:`PyEval_SaveThread` و :c:func:`PyEval_RestoreThread`"

msgid ":c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS`"
msgstr ":c:macro:`Py_BEGIN_ALLOW_THREADS` و :c:macro:`Py_END_ALLOW_THREADS`"

msgid "These functions should still be used in the free-threaded build to manage thread state even when the :term:`GIL` is disabled.  For example, if you create a thread outside of Python, you must call :c:func:`PyThreadState_Ensure` before calling into the Python API to ensure that the thread has a valid Python thread state."
msgstr "این توابع همچنان باید در ساخت نخ‌آزاد برای مدیریت وضعیت نخ حتی زمانی که :term:`GIL` غیرفعال است، استفاده شوند. برای مثال، اگر نخی را خارج از پایتون ایجاد کنید، باید پیش از فراخوانی API پایتون، تابع :c:func:`PyThreadState_Ensure` را فراخوانی کنید تا مطمئن شوید که نخ دارای وضعیت نخ معتبری در پایتون است."

msgid "You should continue to call :c:func:`PyEval_SaveThread` or :c:macro:`Py_BEGIN_ALLOW_THREADS` around blocking operations, such as I/O or lock acquisitions, to allow other threads to run the :term:`cyclic garbage collector <garbage collection>`."
msgstr "شما باید همچنان :c:func:`PyEval_SaveThread` یا :c:macro:`Py_BEGIN_ALLOW_THREADS` را در اطراف عملیات مسدودکننده، مانند I/O یا کسب قفل، فراخوانی کنید تا نخ‌های دیگر بتوانند :term:`زباله‌روبی چرخه‌ای <garbage collection>` را اجرا کنند."

msgid "Protecting Internal Extension State"
msgstr "محافظت از وضعیت داخلی افزونه"

msgid "Your extension may have internal state that was previously protected by the GIL.  You may need to add locking to protect this state.  The approach will depend on your extension, but some common patterns include:"
msgstr "ممکن است افزونه شما وضعیت داخلی داشته باشد که پیش‌تر توسط GIL محافظت می‌شد. ممکن است لازم باشد برای محافظت از این وضعیت، قفل‌گذاری اضافه کنید. رویکرد مورد استفاده به افزونه شما بستگی دارد، اما برخی الگوهای رایج عبارت‌اند از:"

msgid "**Caches**: global caches are a common source of shared state.  Consider using a lock to protect the cache or disabling it in the free-threaded build if the cache is not critical for performance."
msgstr "**نهانگاه‌ها**: نهانگاه‌های سراسری منبع رایجی از وضعیت مشترک هستند. اگر نهانگاه برای کارایی حیاتی نیست، استفاده از یک قفل برای محافظت از نهانگاه یا غیرفعال کردن آن در ساخت نخ‌آزاد را در نظر بگیرید."

msgid "**Global State**: global state may need to be protected by a lock or moved to thread local storage. C11 and C++11 provide the ``thread_local`` or ``_Thread_local`` for `thread-local storage <https://en.cppreference.com/w/c/language/storage_duration>`_."
msgstr "**وضعیت سراسری**: ممکن است لازم باشد وضعیت سراسری با یک قفل محافظت شود یا به فضای ذخیره‌سازی محلی نخ منتقل شود. C11 و C++11 برای `فضای ذخیره‌سازی محلی نخ <https://en.cppreference.com/w/c/language/storage_duration>`_، ``thread_local`` یا ``_Thread_local`` را ارائه می‌کنند."

msgid "Critical Sections"
msgstr "بخش‌های بحرانی"

msgid "In the free-threaded build, CPython provides a mechanism called \"critical sections\" to protect data that would otherwise be protected by the GIL. While extension authors may not interact with the internal critical section implementation directly, understanding their behavior is crucial when using certain C API functions or managing shared state in the free-threaded build."
msgstr "در ساخت نخ‌آزاد (free-threaded build)، CPython برای محافظت از داده‌هایی که در غیر این صورت توسط GIL محافظت می‌شدند، سازوکاری به نام «بخش‌های بحرانی» فراهم می‌کند. اگرچه ممکن است نویسندگان افزونه‌ها مستقیماً با پیاده‌سازی داخلی بخش‌های بحرانی تعامل نداشته باشند، درک رفتار آن‌ها هنگام استفاده از برخی از توابع C API یا مدیریت وضعیت مشترک در ساخت نخ‌آزاد بسیار مهم است."

msgid "What Are Critical Sections?"
msgstr "بخش‌های بحرانی چیستند؟"

msgid "Conceptually, critical sections act as a deadlock avoidance layer built on top of simple mutexes. Each thread maintains a stack of active critical sections. When a thread needs to acquire a lock associated with a critical section (e.g., implicitly when calling a thread-safe C API function like :c:func:`PyDict_SetItem`, or explicitly using macros), it attempts to acquire the underlying mutex."
msgstr "از نظر مفهومی، بخش‌های بحرانی به‌عنوان لایه‌ای برای اجتناب از بن‌بست عمل می‌کنند که بر روی قفل‌های متقابل ساده (mutex) ساخته شده‌اند. هر نخ، پشته‌ای از بخش‌های بحرانی فعال را نگه می‌دارد. هرگاه نخی نیاز به کسب قفلی مرتبط با یک بخش بحرانی داشته باشد (برای مثال، به‌صورت ضمنی هنگام فراخوانی تابعی ایمن برای نخ از API C مانند :c:func:`PyDict_SetItem`، یا به‌صورت صریح با استفاده از ماکروها)، تلاش می‌کند قفل متقابل زیربنایی را کسب کند."

msgid "Using Critical Sections"
msgstr "استفاده از بخش‌های بحرانی"

msgid "The primary APIs for using critical sections are:"
msgstr "APIهای اصلی برای استفاده از بخش‌های بحرانی عبارتند از:"

msgid ":c:macro:`Py_BEGIN_CRITICAL_SECTION` and :c:macro:`Py_END_CRITICAL_SECTION` - For locking a single object"
msgstr ":c:macro:`Py_BEGIN_CRITICAL_SECTION` و :c:macro:`Py_END_CRITICAL_SECTION` - برای قفل‌کردن یک شیء واحد"

msgid ":c:macro:`Py_BEGIN_CRITICAL_SECTION2` and :c:macro:`Py_END_CRITICAL_SECTION2` - For locking two objects simultaneously"
msgstr ":c:macro:`Py_BEGIN_CRITICAL_SECTION2` و :c:macro:`Py_END_CRITICAL_SECTION2` - برای قفل کردن همزمان دو شیء"

msgid "These macros must be used in matching pairs and must appear in the same C scope, since they establish a new local scope.  These macros are no-ops in non-free-threaded builds, so they can be safely added to code that needs to support both build types."
msgstr "این ماکروها باید به‌صورت جفت‌های متناظر استفاده شوند و در یک محدوده C یکسان ظاهر شوند، زیرا آن‌ها یک محدوده محلی جدید ایجاد می‌کنند. این ماکروها در ساخت‌های non-free-threaded بدون عملیات هستند، بنابراین می‌توان آن‌ها را با اطمینان به کدی که نیاز به پشتیبانی از هر دو نوع ساخت دارد، اضافه کرد."

msgid "A common use of a critical section would be to lock an object while accessing an internal attribute of it.  For example, if an extension type has an internal count field, you could use a critical section while reading or writing that field::"
msgstr "یک استفاده رایج از بخش بحرانی این است که هنگام دسترسی به یک ویژگی داخلی یک شیء، آن شیء را قفل کنید. برای مثال، اگر یک نوع توسعه‌ای دارای یک فیلد شمارش داخلی باشد، می‌توانید هنگام خواندن یا نوشتن آن فیلد از یک بخش بحرانی استفاده کنید::"

msgid ""
"// read the count, returns new reference to internal count value\n"
"PyObject *result;\n"
"Py_BEGIN_CRITICAL_SECTION(obj);\n"
"result = Py_NewRef(obj->count);\n"
"Py_END_CRITICAL_SECTION();\n"
"return result;\n"
"\n"
"// write the count, consumes reference from new_count\n"
"Py_BEGIN_CRITICAL_SECTION(obj);\n"
"obj->count = new_count;\n"
"Py_END_CRITICAL_SECTION();"
msgstr ""
"// خواندن count، یک ارجاع جدید به مقدار داخلی count برمی‌گرداند\n"
"PyObject *result;\n"
"Py_BEGIN_CRITICAL_SECTION(obj);\n"
"result = Py_NewRef(obj->count);\n"
"Py_END_CRITICAL_SECTION();\n"
"return result;\n"
"\n"
"// نوشتن count، ارجاع new_count را مصرف می‌کند\n"
"Py_BEGIN_CRITICAL_SECTION(obj);\n"
"obj->count = new_count;\n"
"Py_END_CRITICAL_SECTION();"

msgid "How Critical Sections Work"
msgstr "نحوه کار بخش‌های بحرانی"

msgid "Unlike traditional locks, critical sections do not guarantee exclusive access throughout their entire duration. If a thread would block while holding a critical section (e.g., by acquiring another lock or performing I/O), the critical section is temporarily suspended—all locks are released—and then resumed when the blocking operation completes."
msgstr "برخلاف قفل‌های سنتی، بخش‌های بحرانی دسترسی انحصاری را در تمام مدت خود تضمین نمی‌کنند. اگر نخی در حالی که یک بخش بحرانی را در اختیار دارد مسدود شود (مثلاً با به دست آوردن قفلی دیگر یا انجام I/O)، آن بخش بحرانی به‌طور موقت معلق می‌شود—همه قفل‌ها آزاد می‌شوند—و سپس هنگامی که عملیات مسدودکننده کامل شود، از سر گرفته می‌شود."

msgid "This behavior is similar to what happens with the GIL when a thread makes a blocking call. The key differences are:"
msgstr "این رفتار مشابه اتفاقی است که با GIL هنگامی رخ می‌دهد که یک نخ یک فراخوانی مسدودکننده انجام می‌دهد. تفاوت‌های اصلی عبارتند از:"

msgid "Critical sections operate on a per-object basis rather than globally"
msgstr "بخش‌های بحرانی به‌ازای هر شیء عمل می‌کنند، نه به‌صورت سراسری"

msgid "Critical sections follow a stack discipline within each thread (the \"begin\" and \"end\" macros enforce this since they must be paired and within the same scope)"
msgstr "بخش‌های بحرانی در هر نخ از یک نظم پشته‌ای پیروی می‌کنند (ماکروهای «begin» و «end» این موضوع را اعمال می‌کنند، زیرا باید به‌صورت جفت و در یک محدوده یکسان استفاده شوند)"

msgid "Critical sections automatically release and reacquire locks around potential blocking operations"
msgstr "بخش‌های بحرانی به‌طور خودکار قفل‌ها را پیرامون عملیات‌های مسدودکننده‌ی احتمالی آزاد کرده و دوباره تصاحب می‌کنند"

msgid "Deadlock Avoidance"
msgstr "اجتناب از بن‌بست"

msgid "Critical sections help avoid deadlocks in two ways:"
msgstr "بخش‌های بحرانی به دو روش در جلوگیری از بن‌بست‌ها کمک می‌کنند:"

msgid "If a thread tries to acquire a lock that's already held by another thread, it first suspends all of its active critical sections, temporarily releasing their locks"
msgstr "اگر یک نخ تلاش کند قفلی را که از قبل در اختیار نخ دیگری است به دست آورد، ابتدا تمام بخش‌های بحرانی فعال خود را معلق می‌کند و قفل‌های آن‌ها را به‌طور موقت آزاد می‌کند"

msgid "When the blocking operation completes, only the top-most critical section is reacquired first"
msgstr "هنگامی که عملیات مسدودکننده کامل می‌شود، ابتدا تنها بالاترین بخش بحرانی دوباره به دست می‌آید"

msgid "This means you cannot rely on nested critical sections to lock multiple objects at once, as the inner critical section may suspend the outer ones. Instead, use :c:macro:`Py_BEGIN_CRITICAL_SECTION2` to lock two objects simultaneously."
msgstr "این بدان معناست که نمی‌توانید برای قفل کردن چندین شیء به‌طور همزمان، به بخش‌های بحرانی تودرتو اتکا کنید، زیرا بخش بحرانی داخلی ممکن است بخش‌های بحرانی بیرونی را معلق کند. در عوض، برای قفل کردن همزمان دو شیء از :c:macro:`Py_BEGIN_CRITICAL_SECTION2` استفاده کنید."

msgid "Note that the locks described above are only :c:type:`PyMutex` based locks. The critical section implementation does not know about or affect other locking mechanisms that might be in use, like POSIX mutexes.  Also note that while blocking on any :c:type:`PyMutex` causes the critical sections to be suspended, only the mutexes that are part of the critical sections are released.  If :c:type:`PyMutex` is used without a critical section, it will not be released and therefore does not get the same deadlock avoidance."
msgstr "توجه داشته باشید که قفل‌های توصیف‌شده در بالا فقط قفل‌های مبتنی بر :c:type:`PyMutex` هستند. پیاده‌سازی بخش بحرانی از سایر سازوکارهای قفل‌سازی که ممکن است در حال استفاده باشند، مانند قفل‌های متقابل POSIX، آگاه نیست و آن‌ها را تحت تأثیر قرار نمی‌دهد. همچنین توجه داشته باشید که هرچند مسدود شدن در انتظار هر :c:type:`PyMutex` باعث تعلیق بخش‌های بحرانی می‌شود، فقط قفل‌های متقابلی که بخشی از بخش‌های بحرانی هستند آزاد می‌شوند. اگر :c:type:`PyMutex` بدون یک بخش بحرانی استفاده شود، آزاد نخواهد شد و بنابراین از همان اجتناب از بن‌بست بهره‌مند نمی‌شود."

msgid "Important Considerations"
msgstr "ملاحظات مهم"

msgid "Critical sections may temporarily release their locks, allowing other threads to modify the protected data. Be careful about making assumptions about the state of the data after operations that might block."
msgstr "بخش‌های بحرانی ممکن است قفل‌های خود را به‌طور موقت آزاد کنند و به نخ‌های دیگر اجازه دهند داده‌های محافظت‌شده را تغییر دهند. هنگام فرض‌سازی درباره وضعیت داده‌ها پس از عملیاتی که ممکن است مسدودکننده باشند، احتیاط کنید."

msgid "Because locks can be temporarily released (suspended), entering a critical section does not guarantee exclusive access to the protected resource throughout the section's duration. If code within a critical section calls another function that blocks (e.g., acquires another lock, performs blocking I/O), all locks held by the thread via critical sections will be released. This is similar to how the GIL can be released during blocking calls."
msgstr "چون قفل‌ها می‌توانند به‌طور موقت آزاد (معلق) شوند، ورود به یک بخش بحرانی، دسترسی انحصاری به منبع محافظت‌شده را در تمام مدت آن بخش تضمین نمی‌کند. اگر کد درون یک بخش بحرانی تابع دیگری را فراخوانی کند که مسدودکننده است (برای مثال، قفل دیگری را به دست می‌آورد یا ورودی/خروجی مسدودکننده انجام می‌دهد)، تمام قفل‌هایی که نخ از طریق بخش‌های بحرانی در اختیار دارد آزاد خواهند شد. این شبیه به حالتی است که GIL می‌تواند در حین فراخوانی‌های مسدودکننده آزاد شود."

msgid "Only the lock(s) associated with the most recently entered (top-most) critical section are guaranteed to be held at any given time. Locks for outer, nested critical sections might have been suspended."
msgstr "تنها قفل(ها)ی مرتبط با آخرین بخش بحرانی واردشده (بالاترین) تضمین می‌شود که در هر لحظه نگه‌داشته شده باشند. قفل‌های بخش‌های بحرانی بیرونی و تودرتو ممکن است معلق شده باشند."

msgid "You can lock at most two objects simultaneously with these APIs. If you need to lock more objects, you'll need to restructure your code."
msgstr "شما می‌توانید با این APIها حداکثر ۲ شیء را به‌طور همزمان قفل کنید. اگر نیاز دارید اشیاء بیشتری را قفل کنید، باید ساختار کد خود را بازآرایی کنید."

msgid "While critical sections will not deadlock if you attempt to lock the same object twice, they are less efficient than purpose-built reentrant locks for this use case."
msgstr "اگرچه بخش‌های بحرانی در صورت تلاش برای قفل کردن دوباره‌ی یک شیء دچار بن‌بست نمی‌شوند، اما برای این مورد استفاده، کارآمدی کمتری نسبت به قفل‌های بازورودپذیر (reentrant locks) دارند که برای همین منظور ساخته شده‌اند."

msgid "When using :c:macro:`Py_BEGIN_CRITICAL_SECTION2`, the order of the objects doesn't affect correctness (the implementation handles deadlock avoidance), but it's good practice to always lock objects in a consistent order."
msgstr "هنگام استفاده از :c:macro:`Py_BEGIN_CRITICAL_SECTION2`، ترتیب شیء‌ها بر صحت تأثیر نمی‌گذارد (پیاده‌سازی اجتناب از بن‌بست را مدیریت می‌کند)، اما بهتر است همیشه شیء‌ها را با ترتیبی ثابت قفل کنید."

msgid "Remember that the critical section macros are primarily for protecting access to *Python objects* that might be involved in internal CPython operations susceptible to the deadlock scenarios described above. For protecting purely internal extension state, standard mutexes or other synchronization primitives might be more appropriate."
msgstr "به یاد داشته باشید که ماکروهای بخش بحرانی عمدتاً برای محافظت از دسترسی به *اشیای پایتون* به کار می‌روند؛ این اشیاء ممکن است در عملیات داخلی CPython که مستعد سناریوهای بن‌بست توصیف‌شده در بالا هستند، دخیل باشند. برای محافظت از وضعیت کاملاً داخلی افزونه، ممکن است قفل‌های متقابل استاندارد یا دیگر سازوکارهای همگام‌سازی مناسب‌تر باشند."

msgid "Per-Object Locks (``ob_mutex``)"
msgstr "قفل‌های مخصوص هر شیء (``ob_mutex``)"

msgid "In the free-threaded build, each Python object contains a :c:member:`~PyObject.ob_mutex` field of type :c:type:`PyMutex`.  This mutex is **reserved for use by the critical section API** (:c:macro:`Py_BEGIN_CRITICAL_SECTION` / :c:macro:`Py_END_CRITICAL_SECTION`)."
msgstr "در ساخت نخ‌آزاد، هر شیء پایتون شامل یک فیلد :c:member:`~PyObject.ob_mutex` از نوع :c:type:`PyMutex` است. این قفل متقابل **برای استفاده توسط API بخش بحرانی** (:c:macro:`Py_BEGIN_CRITICAL_SECTION` / :c:macro:`Py_END_CRITICAL_SECTION`) **رزرو شده است**."

msgid "Do **not** lock ``ob_mutex`` directly with ``PyMutex_Lock(&obj->ob_mutex)``. Mixing direct ``PyMutex_Lock`` calls with the critical section API on the same mutex can cause deadlocks."
msgstr "``ob_mutex`` را مستقیماً با ``PyMutex_Lock(&obj->ob_mutex)`` قفل **نکنید**. ترکیب فراخوانی‌های مستقیم ``PyMutex_Lock`` با API بخش بحرانی روی همان قفل متقابل می‌تواند باعث ایجاد بن‌بست شود."

msgid "Even if your own code never uses critical sections on a particular object type, **CPython internals may use the critical section API on any Python object**."
msgstr "حتی اگر کد خودتان هرگز از بخش‌های بحرانی روی یک نوع شیء خاص استفاده نکند، **بخش‌های داخلی سی‌پایتون ممکن است از API بخش بحرانی روی هر شیء پایتونی استفاده کنند**."

msgid "If your extension type needs its own lock, add a separate :c:type:`PyMutex` field (or another synchronization primitive) to your object struct. :c:type:`PyMutex` is very lightweight, so there is negligible cost to having an additional one."
msgstr "اگر نوع افزونه‌ی شما به قفل خودش نیاز دارد، یک فیلد مجزای :c:type:`PyMutex` (یا یک اولیه‌ی همگام‌سازی دیگر) به ساختار شیء خود اضافه کنید. :c:type:`PyMutex` بسیار سبک است، بنابراین داشتن یک قفل اضافی هزینه‌ی ناچیزی دارد."

msgid "Building Extensions for the Free-Threaded Build"
msgstr "ساخت افزونه‌ها برای ساخت نخ‌آزاد (Free-Threaded Build)"

msgid "C API extensions need to be built specifically for the free-threaded build. The wheels, shared libraries, and binaries are indicated by a ``t`` suffix."
msgstr "افزونه‌های C API باید به‌طور خاص برای ساخت نخ‌آزادی ساخته شوند. wheelها، کتابخانه‌های مشترک و دودویی‌ها با پسوند ``t`` مشخص می‌شوند."

msgid "`pypa/manylinux <https://github.com/pypa/manylinux>`_ supports the free-threaded build, with the ``t`` suffix, such as ``python3.14t``."
msgstr "`pypa/manylinux <https://github.com/pypa/manylinux>`_ از ساخت نخ‌آزاد (free-threaded) با پسوند ``t``، مانند ``python3.14t``، پشتیبانی می‌کند."

msgid "`pypa/cibuildwheel <https://github.com/pypa/cibuildwheel>`_ supports building wheels for the free-threaded build of Python 3.14 and newer."
msgstr "`pypa/cibuildwheel <https://github.com/pypa/cibuildwheel>`_ از ساخت wheelها برای نسخه‌ی ساخت نخ‌آزادی پایتون 3.14 و جدیدتر پشتیبانی می‌کند."

msgid "Limited C API and Stable ABI"
msgstr "API محدود C و ABI پایدار"

msgid "The free-threaded build does not currently support the :ref:`Limited C API <limited-c-api>` or the stable ABI.  If you use `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`_ to build your extension and currently set ``py_limited_api=True`` you can use ``py_limited_api=not sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` to opt out of the limited API when building with the free-threaded build."
msgstr "ساخت نخ‌آزادی (free-threaded build) در حال حاضر از :ref:`Limited C API <limited-c-api>` یا ABI پایدار پشتیبانی نمی‌کند. اگر برای ساخت افزونه خود از `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`_ استفاده می‌کنید و در حال حاضر ``py_limited_api=True`` را تنظیم کرده‌اید، می‌توانید برای خارج شدن از API محدود هنگام ساخت با ساخت نخ‌آزادی، از ``py_limited_api=not sysconfig.get_config_var(\"Py_GIL_DISABLED\")`` استفاده کنید."

msgid "You will need to build separate wheels specifically for the free-threaded build.  If you currently use the stable ABI, you can continue to build a single wheel for multiple non-free-threaded Python versions."
msgstr "شما باید wheelهای جداگانه‌ای را به‌طور خاص برای ساخت نخ‌آزاد  بسازید. اگر در حال حاضر از ABI پایدار استفاده می‌کنید، می‌توانید به ساخت یک wheel واحد برای چندین نسخه‌ی پایتون غیرنخ‌آزاد (non-free-threaded) ادامه دهید."

msgid "Windows"
msgstr "ویندوز"

msgid "Due to a limitation of the official Windows installer, you will need to manually define ``Py_GIL_DISABLED=1`` when building extensions from source."
msgstr "به دلیل محدودیتی در نصب‌کننده رسمی ویندوز، هنگام ساخت افزونه‌ها از منبع، باید به‌صورت دستی ``Py_GIL_DISABLED=1`` را تعریف کنید."

msgid "`Porting Extension Modules to Support Free-Threading <https://py-free-threading.github.io/porting/>`_: A community-maintained porting guide for extension authors."
msgstr "`پورت ماژول‌های توسعه‌ای برای پشتیبانی از Free-Threading <https://py-free-threading.github.io/porting/>`_: یک راهنمای پورت نگهداری‌شده توسط کامیونیتی برای نویسندگان افزونه."