اشیاء ارجاع ضعیف

پایتون از ارجاع‌های ضعیف به‌عنوان اشیاء درجه یک پشتیبانی می‌کند. دو نوع شیء مشخص وجود دارند که ارجاع‌های ضعیف را مستقیماً پیاده‌سازی می‌کنند. نوع اول یک شیء ارجاع ساده است و نوع دوم تا جایی که می‌تواند، به‌عنوان پراکسی برای شیء اصلی عمل می‌کند.

int PyWeakref_Check(PyObject *ob)

اگر ob یا یک ارجاع باشد یا یک شیء پراکسی، مقدار غیرصفر برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyWeakref_CheckRef(PyObject *ob)

اگر ob یک شیء ارجاع یا زیرکلاسی از نوع ارجاع باشد، مقدار غیر صفر برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyWeakref_CheckRefExact(PyObject *ob)

اگر ob یک شیء ارجاع باشد اما زیرکلاسی از نوع ارجاع نباشد، مقدار ناصفر برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

int PyWeakref_CheckProxy(PyObject *ob)

اگر ob یک شیء پراکسی باشد، مقدار غیرصفر برمی‌گرداند. این تابع همیشه موفق می‌شود.

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)

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

یک شیء ارجاع ضعیف برای شیء ob برمی‌گرداند. این تابع همیشه یک ارجاع جدید برمی‌گرداند، اما تضمین نمی‌شود که شیء جدیدی ایجاد کند؛ ممکن است یک شیء ارجاع موجود برگردانده شود. پارامتر دوم، callback، می‌تواند یک شیء فراخوانی‌پذیر باشد که هنگام زباله‌روبی ob اعلان دریافت می‌کند؛ این شیء باید یک پارامتر واحد بپذیرد که خودِ شیء ارجاع ضعیف خواهد بود. callback همچنین می‌تواند None یا NULL باشد. اگر ob شیئی نباشد که بتوان ارجاع ضعیفی به آن ایجاد کرد، این تابع استثنای TypeError را ایجاد می‌کند و NULL برمی‌گرداند.

همچنین ملاحظه نمائید

PyType_SUPPORTS_WEAKREFS() برای بررسی اینکه آیا ob قابل ارجاع ضعیف است.

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)

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

یک شیء پراکسی ارجاع ضعیف برای شیء ob برمی‌گرداند. این تابع همیشه یک ارجاع جدید برمی‌گرداند، اما تضمین‌شده نیست که شیء جدیدی ایجاد کند؛ ممکن است یک شیء پراکسی موجود برگردانده شود. پارامتر دوم، callback، می‌تواند یک شیء فراخوانی‌پذیر باشد که هنگام زباله‌روبی شدن ob اطلاع‌رسانی دریافت می‌کند؛ باید یک پارامتر واحد بپذیرد که خودِ شیء ارجاع ضعیف خواهد بود. callback همچنین می‌تواند None یا NULL باشد. اگر ob شیء ارجاع ضعیف‌پذیری نباشد، این تابع TypeError ایجاد می‌کند و NULL برمی‌گرداند.

همچنین ملاحظه نمائید

PyType_SUPPORTS_WEAKREFS() برای بررسی اینکه آیا ob قابل ارجاع ضعیف است.

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)

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

یک strong reference به شیء مورد ارجاع را از یک ارجاع ضعیف، ref، در *pobj قرار دهید.

• در صورت موفقیت، *pobj را به یک strong reference جدید به شیء مورد ارجاع تنظیم می‌کند و ۱ را برمی‌گرداند.

• اگر ارجاع مرده باشد، *pobj را برابر NULL قرار دهید و 0 را برگردانید.

• در صورت خطا، یک استثنا برانگیخته و -1 بازگردانده می‌شود.

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

PyObject *PyWeakref_GetObject(PyObject *ref)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار.

یک ارجاع امانتی به شیء ارجاع‌شده را از یک ارجاع ضعیف، ref، برمی‌گرداند. اگر ارجاع‌شونده دیگر زنده نباشد، Py_None را برمی‌گرداند.

توجه

این تابع یک ارجاع امانتی به شیء مورد ارجاع برمی‌گرداند. این بدان معناست که شما باید همیشه Py_INCREF() را روی شیء فراخوانی کنید، مگر اینکه نتوان آن را پیش از آخرین استفاده از ارجاع امانتی نابود کرد.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن از PyWeakref_GetRef() استفاده کنید.

PyObject *PyWeakref_GET_OBJECT(PyObject *ref)

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

مشابه PyWeakref_GetObject()، اما هیچ بررسی خطایی انجام نمی‌دهد.

منسوخ شده از نسخه‌ی 3.13, در نسخه‌ی 3.15 حذف خواهد شد: به جای آن از PyWeakref_GetRef() استفاده کنید.

int PyWeakref_IsDead(PyObject *ref)

بررسی می‌کند که آیا ارجاع ضعیف ref مرده است. اگر ارجاع مرده باشد 1 را برمی‌گرداند، اگر زنده باشد 0 را، و اگر ref یک شیء ارجاع ضعیف نباشد، -1 را همراه با تنظیم خطا برمی‌گرداند.

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

void PyObject_ClearWeakRefs(PyObject *object)

قسمتی از ABI پایدار.

این تابع توسط هندلر tp_dealloc برای پاک‌سازی ارجاع‌های ضعیف فراخوانی می‌شود.

این تابع ارجاع‌های ضعیفِ object را پیمایش می‌کند و برای ارجاع‌هایی که کال‌بک دارند، کال‌بک‌هایشان را فراخوانی می‌کند. این تابع وقتی بازمی‌گردد که تلاش برای همه‌ی کال‌بک‌ها انجام شده باشد.

void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)

این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

ارجاع‌های ضعیف مربوط به object را بدون فراخوانی کال‌بک‌ها پاک‌سازی می‌کند.

این تابع توسط هندلر tp_dealloc برای نوع‌هایی که نهایی‌ساز دارند (یعنی __del__()) فراخوانی می‌شود. هندلر این اشیاء ابتدا PyObject_ClearWeakRefs() را برای پاک کردن ارجاع‌های ضعیف و فراخوانی کال‌بک‌های آن‌ها فراخوانی می‌کند، سپس نهایی‌ساز را اجرا می‌کند و در نهایت این تابع را برای پاک کردن هر ارجاع ضعیفی که ممکن است توسط نهایی‌ساز ایجاد شده باشد فراخوانی می‌کند.

در بیشتر موارد، استفاده از PyObject_ClearWeakRefs() برای پاک کردن ارجاع‌های ضعیف به‌جای این تابع مناسب‌تر است.

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