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

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

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 پایدار.

Return a weak reference object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referenceable object, or if callback is not callable, None, or NULL, this will raise TypeError and return NULL.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Raise TypeError if callback is not callable, None, or NULL.

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

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

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

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

Return a weak reference proxy object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly referenceable object, or if callback is not callable, NULL, this will raise TypeError and return NULL.

تغییر یافته در نسخه‌ی 3.16.0a0 (unreleased): Raise TypeError if callback is not callable, None, or 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.

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.