gc --- رابط زباله‌رو¶

این ماژول رابطی برای جمع‌آور زباله اختیاری فراهم می‌کند. این ماژول توانایی غیرفعال کردن جمع‌آور، تنظیم بسامد جمع‌آوری و تنظیم گزینه‌های اشکال‌زدایی را فراهم می‌کند. همچنین به اشیای غیرقابل‌دسترسی که جمع‌آور آن‌ها را پیدا کرده است اما نمی‌تواند آزاد کند، دسترسی می‌دهد. از آنجا که جمع‌آور، شمارش ارجاعی را که از قبل در پایتون استفاده می‌شود تکمیل می‌کند، اگر مطمئن هستید برنامه شما چرخه‌های ارجاع ایجاد نمی‌کند، می‌توانید جمع‌آور را غیرفعال کنید. جمع‌آوری خودکار می‌تواند با فراخوانی gc.disable() غیرفعال شود. برای اشکال‌زدایی یک برنامه دارای نشتی، gc.set_debug(gc.DEBUG_LEAK) را فراخوانی کنید. توجه داشته باشید که این شامل gc.DEBUG_SAVEALL نیز می‌شود و باعث می‌شود اشیای زباله‌روبی‌شده در gc.garbage برای بازرسی ذخیره شوند.

ماژول gc توابع زیر را فراهم می‌کند:

gc.enable()¶

فعال‌سازی زباله‌روبی خودکار.

gc.disable()¶

غیرفعال‌سازی زباله‌روبی خودکار.

gc.isenabled()¶

اگر زباله‌روبی خودکار فعال باشد، True را برمی‌گرداند.

gc.collect(generation=2)¶

بدون آرگومان، یک زباله‌روبی کامل اجرا می‌شود. آرگومان اختیاری generation می‌تواند یک عدد صحیح باشد که مشخص می‌کند کدام نسل باید زباله‌روبی شود (از ۰ تا ۲). اگر شماره نسل نامعتبر باشد، یک ValueError پرتاب می‌شود. مجموع اشیای جمع‌آوری‌شده و اشیای غیرقابل جمع‌آوری برگردانده می‌شود.

هر زمان که یک زباله‌روبی کامل یا زباله‌روبی بالاترین نسل (۲) اجرا شود، فهرست‌های آزاد (free lists) که برای تعدادی از انواع توکار نگهداری می‌شوند، پاک می‌شوند. ممکن است به دلیل جزئیات پیاده‌سازی، همه‌ی آیتم‌های موجود در برخی فهرست‌های آزاد آزاد نشوند، به‌ویژه در مورد float.

اثر فراخوانی gc.collect() در حالی که مفسر از قبل در حال انجام زباله‌روبی است، تعریف‌نشده است.

تغییر یافته در نسخه‌ی 3.14: generation=1 یک افزایش زباله‌روبی را انجام می‌دهد.

تغییر یافته در نسخه‌ی 3.14.5: generation=1 زباله‌روبی نسل میانی را انجام می‌دهد.

gc.set_debug(flags)¶

پرچم‌های اشکال‌زدایی زباله‌روبی را تنظیم کنید. اطلاعات اشکال‌زدایی در sys.stderr نوشته خواهد شد. برای مشاهده فهرستی از پرچم‌های اشکال‌زدایی که می‌توان آن‌ها را با استفاده از عملیات بیتی برای کنترل اشکال‌زدایی ترکیب کرد، به ادامه مراجعه کنید.

gc.get_debug()¶

پرچم‌های اشکال‌زدایی را که در حال حاضر تنظیم شده‌اند، برمی‌گرداند.

gc.get_objects(generation=None)¶

فهرستی از تمام اشیای پیگیری‌شده توسط جمع‌کننده را بازمی‌گرداند، به‌جز فهرست برگردانده‌شده. اگر generation برابر None نباشد، فقط اشیای پیگیری‌شده توسط جمع‌کننده را که در آن نسل قرار دارند، بازمی‌گرداند.

هشدار

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

تغییر یافته در نسخه‌ی 3.8: پارامتر generation جدید.

تغییر یافته در نسخه‌ی 3.14: نسل ۱ حذف می‌شود

تغییر یافته در نسخه‌ی 3.14.5: نسل ۱ دوباره معرفی شده است تا رفتار زباله‌روبی از 3.13 حفظ شود.

یک رویداد حسابرسی gc.get_objects را با آرگومان generation پرتاب می‌کند.

gc.get_stats()¶

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

• collections تعداد دفعاتی است که این نسل جمع‌آوری شده است؛

• collected تعداد کل اشیایی است که در این نسل جمع‌آوری شده‌اند؛

• uncollectable تعداد کل اشیایی است که مشخص شد غیرقابل جمع‌آوری هستند (و بنابراین به فهرست garbage منتقل شدند) در این نسل؛

• candidates تعداد کل اشیا در این نسل است که برای جمع‌آوری در نظر گرفته شده و پیمایش شدند؛

• duration کل زمان بر حسب ثانیه است که صرف جمع‌آوری‌های این نسل شده است.

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

تغییر یافته در نسخه‌ی 3.15: اضافه کردن duration و candidates.

gc.set_threshold(threshold0[, threshold1[, threshold2]])¶

آستانه‌های زباله‌روبی (فرکانس جمع‌آوری) را تنظیم کنید. قرار دادن threshold0 روی ۰، جمع‌آوری را غیرفعال می‌کند.

GC اشیاء را بسته به اینکه از چند دور زباله‌روبی جان به در برده‌اند، به سه نسل طبقه‌بندی می‌کند. اشیاء جدید در جوان‌ترین نسل (نسل 0) قرار می‌گیرند. اگر شیء از یک زباله‌روبی جان به در ببرد، به نسل قدیمی‌تر بعدی منتقل می‌شود. از آنجا که نسل 2 قدیمی‌ترین نسل است، اشیاء موجود در آن نسل پس از زباله‌روبی در همان‌جا باقی می‌مانند. جمع‌کننده برای تصمیم‌گیری درباره زمان اجرا، تعداد تخصیص‌ها و آزادسازی‌های اشیاء از آخرین زباله‌روبی را پیگیری می‌کند. هنگامی که تعداد تخصیص‌ها منهای تعداد آزادسازی‌ها از threshold0 بیشتر شود، زباله‌روبی آغاز می‌شود. در ابتدا فقط نسل 0 بررسی می‌شود. اگر نسل 0 از زمانی که نسل 1 بررسی شده است بیش از threshold1 بار بررسی شده باشد، نسل 1 نیز بررسی می‌شود. در مورد نسل سوم، اوضاع کمی پیچیده‌تر است؛ برای اطلاعات بیشتر جمع‌آوری قدیمی‌ترین نسل را ببینید.

برای اطلاعات بیشتر به طراحی جمع‌آوری‌کننده‌ی زباله مراجعه کنید.

تغییر یافته در نسخه‌ی 3.14: threshold2 نادیده گرفته می‌شود

تغییر یافته در نسخه‌ی 3.14.5: threshold2 برای مطابقت با رفتار پایتون 3.13 بازگردانده شده است.

gc.get_count()¶

شمارش‌های فعلی جمع‌آوری را به‌صورت یک تاپل از (count0, count1, count2) برمی‌گرداند.

gc.get_threshold()¶

آستانه‌های فعلی زباله‌روبی را به‌صورت تاپلی از (threshold0, threshold1, threshold2) برمی‌گرداند.

gc.get_referrers(*objs)¶

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

توجه داشته باشید که اشیایی که قبلاً ارجاع‌زدایی شده‌اند، اما در چرخه‌ها قرار دارند و هنوز توسط زباله‌روب جمع‌آوری نشده‌اند، ممکن است در میان ارجاع‌دهنده‌های نتیجه فهرست شوند. برای دریافت فقط اشیای زنده‌ی فعلی، پیش از فراخوانی get_referrers()، collect() را فراخوانی کنید.

هشدار

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

یک رویداد حسابرسی gc.get_referrers را با آرگومان objs پرتاب می‌کند.

gc.get_referents(*objs)¶

فهرستی از اشیایی را برمی‌گرداند که به‌طور مستقیم توسط هر یک از آرگومان‌ها به آن‌ها ارجاع‌شده‌اند. موارد ارجاع‌شده‌ی بازگشتی همان اشیایی هستند که توسط متدهای tp_traverse آرگومان‌ها در سطح C (در صورت وجود) بازدید شده‌اند، و ممکن است همه‌ی اشیایی را که واقعاً به‌طور مستقیم قابل دسترسی هستند شامل نشوند. متدهای tp_traverse فقط توسط اشیایی پشتیبانی می‌شوند که از زباله‌روبی پشتیبانی می‌کنند، و فقط لازم است اشیایی را بازدید کنند که ممکن است در یک چرخه دخیل باشند. بنابراین، برای مثال، اگر یک عدد صحیح به‌طور مستقیم از یک آرگومان قابل دسترسی باشد، ممکن است آن شیء عدد صحیح در فهرست نتیجه ظاهر شود یا نشود.

یک رویداد حسابرسی gc.get_referents را با آرگومان objs پرتاب می‌کند.

gc.is_tracked(obj)¶

اگر شیء در حال حاضر توسط زباله‌روبی پیگیری شود، True و در غیر این صورت False برمی‌گرداند. به‌عنوان قاعده‌ای کلی، نمونه‌های انواع اتمی پیگیری نمی‌شوند و نمونه‌های انواع غیراتمی (ظرف‌ها، اشیای تعریف‌شده توسط کاربر...) پیگیری می‌شوند. با این حال، ممکن است برخی بهینه‌سازی‌های مختص نوع وجود داشته باشند تا ردپای زباله‌روبی نمونه‌های ساده را کاهش دهند (برای مثال، دیکشنری‌هایی که تنها کلیدها و مقادیر اتمی دارند):

>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked({})
False
>>> gc.is_tracked({"a": 1})
True

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

gc.is_finalized(obj)¶

اگر شیء داده‌شده توسط زباله‌رو نهایی‌سازی شده باشد، True و در غیر این صورت False برمی‌گرداند.

>>> x = None
>>> class Lazarus:
...     def __del__(self):
...         global x
...         x = self
...
>>> lazarus = Lazarus()
>>> gc.is_finalized(lazarus)
False
>>> del lazarus
>>> gc.is_finalized(x)
True

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

gc.freeze()¶

همه اشیای پیگیری‌شده توسط زباله‌روبی را فریز می‌کند؛ آن‌ها را به یک نسل دائمی منتقل می‌کند و در همه جمع‌آوری‌های آینده نادیده می‌گیرد.

اگر فرایندی fork() را بدون exec() فراخوانی کند، اجتناب از کپی-در-نوشتن (copy-on-write) غیرضروری در فرایندهای فرزند، اشتراک‌گذاری حافظه را بیشینه می‌کند و مصرف کلی حافظه را کاهش می‌دهد. این امر مستلزم دو چیز است: اجتناب از ایجاد «حفره‌های» آزادشده در صفحات حافظه در فرایند والد، و اطمینان از اینکه عملیات‌های زباله‌روبی در فرایندهای فرزند، شمارنده gc_refs اشیاء طولانی‌عمری را که از فرایند والد منشأ گرفته‌اند، تغییر ندهند. برای دستیابی به هر دو مورد، در اوایل فرایند والد gc.disable()، درست قبل از fork() gc.freeze() و در اوایل فرایندهای فرزند gc.enable() را فراخوانی کنید.

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

gc.unfreeze()¶

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

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

gc.get_freeze_count()¶

تعداد شیء‌ها در نسل دائمی را برمی‌گرداند.

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

متغیرهای زیر برای دسترسی فقط‌خواندنی ارائه شده‌اند (می‌توانید مقادیر را تغییر دهید، اما نباید آن‌ها را بازپیوند (rebind) کنید):

gc.garbage¶

فهرستی از اشیایی که زباله‌رو آن‌ها را غیرقابل دسترس تشخیص داده است، اما نتوانسته است آن‌ها را آزاد کند (اشیاء غیرقابل جمع‌آوری). از پایتون 3.4 به بعد، این فهرست باید در بیشتر مواقع خالی باشد، مگر هنگام استفاده از نمونه‌های انواع توسعه‌ای C با جایگاه tp_del غیر NULL.

اگر DEBUG_SAVEALL تنظیم شده باشد، تمام اشیای غیرقابل‌دسترسی به‌جای آزاد شدن، به این فهرست افزوده می‌شوند.

تغییر یافته در نسخه‌ی 3.2: اگر این فهرست در زمان interpreter shutdown خالی نباشد، یک ResourceWarning نشان داده می‌شود که به‌طور پیش‌فرض خاموش است. اگر DEBUG_UNCOLLECTABLE تنظیم شده باشد، علاوه بر این، همه‌ی اشیای غیرقابل جمع‌آوری نیز چاپ می‌شوند.

تغییر یافته در نسخه‌ی 3.4: بر اساس PEP 442، اشیایی که متد __del__() دارند، دیگر در gc.garbage قرار نمی‌گیرند.

gc.callbacks¶

فهرستی از کال‌بک‌ها که توسط جمع‌کننده زباله پیش و پس از زباله‌روبی فراخوانی می‌شوند. این کال‌بک‌ها با دو آرگومان، phase و info فراخوانی می‌شوند.

phase می‌تواند یکی از دو مقدار باشد:

"start": زباله‌روبی در آستانه شروع است.

"stop": زباله‌روبی به پایان رسید.

info یک دیکشنری است که اطلاعات بیشتری برای کال‌بک ارائه می‌دهد. کلیدهای زیر در حال حاضر تعریف شده‌اند:

"generation": قدیمی‌ترین نسلی که در حال جمع‌آوری است.

"collected": هنگامی که phase برابر "stop" باشد، تعداد شیءهایی که با موفقیت جمع‌آوری شده‌اند.

"uncollectable": وقتی phase برابر "stop" است، تعداد اشیایی که جمع‌آوری نشدند و در garbage قرار گرفتند.

"candidates": وقتی phase برابر با "stop" است، تعداد کل اشیا در این نسل که برای جمع‌آوری در نظر گرفته شده و پیمایش شدند.

"duration": وقتی phase برابر با "stop" است، زمان بر حسب ثانیه که صرف جمع‌آوری شده است.

برنامه‌ها می‌توانند کال‌بک‌های خود را به این فهرست اضافه کنند. موارد استفاده اصلی عبارتند از:

جمع‌آوری آمار درباره زباله‌روبی، مانند تعداد دفعات جمع‌آوری نسل‌های مختلف و مدت‌زمان جمع‌آوری.

اجازه دادن به برنامه‌ها برای شناسایی و پاک‌سازی انواع غیرقابل‌جمع‌آوری خودشان، هنگامی که در garbage ظاهر می‌شوند.

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

تغییر یافته در نسخه‌ی 3.15: اضافه کردن "duration" و "candidates".

ثابت‌های زیر برای استفاده با set_debug() ارائه شده‌اند:

gc.DEBUG_STATS¶

چاپ آمار در حین زباله‌روبی. این اطلاعات می‌تواند هنگام تنظیم فرکانس زباله‌روبی مفید باشد.

gc.DEBUG_COLLECTABLE¶

اطلاعات مربوط به اشیای قابل جمع‌آوری یافت‌شده را چاپ می‌کند.

gc.DEBUG_UNCOLLECTABLE¶

اطلاعات اشیای غیرقابل جمع‌آوری یافت‌شده را چاپ می‌کند (اشیایی که قابل دسترس نیستند اما جمع‌کننده نمی‌تواند آن‌ها را آزاد کند). این اشیاء به فهرست garbage افزوده خواهند شد.

تغییر یافته در نسخه‌ی 3.2: همچنین اگر فهرست garbage خالی نباشد، محتویات آن در زمان interpreter shutdown چاپ می‌شود.

gc.DEBUG_SAVEALL¶

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

gc.DEBUG_LEAK¶

پرچم‌های اشکال‌زدایی مورد نیاز برای جمع‌کننده تا اطلاعات مربوط به برنامه‌ای که نشتی دارد را چاپ کند (برابر با DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).