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نباشد، فقط اشیای پیگیریشده توسط جمعکننده را که در آن نسل قرار دارند، بازمیگرداند.تغییر یافته در نسخهی 3.8: پارامتر generation جدید.
تغییر یافته در نسخهی 3.14: نسل ۱ حذف میشود
تغییر یافته در نسخهی 3.14.5: نسل ۱ دوباره معرفی شده است تا رفتار زبالهروبی از 3.13 حفظ شود.
یک رویداد حسابرسی
gc.get_objectsرا با آرگومانgenerationپرتاب میکند.
- gc.get_stats()¶
فهرستی از سه دیکشنری بهازای هر نسل حاوی آمار زبالهروبی از آغاز مفسر برمیگرداند. تعداد کلیدها ممکن است در آینده تغییر کند، اما در حال حاضر هر دیکشنری شامل آیتمهای زیر خواهد بود:
collectionsتعداد دفعاتی است که این نسل جمعآوری شده است؛collectedتعداد کل اشیایی است که در این نسل جمعآوری شدهاند؛uncollectableتعداد کل اشیایی است که در این نسل غیرقابل جمعآوری تشخیص داده شدند (و بنابراین به فهرستgarbageمنتقل شدند).
اضافه شده در نسخهی 3.4.
- gc.set_threshold(threshold0[, threshold1[, threshold2]])¶
آستانههای زبالهروبی (فرکانس جمعآوری) را تنظیم کنید. قرار دادن threshold0 روی ۰، جمعآوری را غیرفعال میکند.
GC اشیاء را بسته به اینکه از چند دور زبالهروبی جان به در بردهاند، به سه نسل طبقهبندی میکند. اشیاء جدید در جوانترین نسل (نسل
0) قرار میگیرند. اگر شیء از یک زبالهروبی جان به در ببرد، به نسل قدیمیتر بعدی منتقل میشود. از آنجا که نسل2قدیمیترین نسل است، اشیاء موجود در آن نسل پس از زبالهروبی در همانجا باقی میمانند. جمعکننده برای تصمیمگیری درباره زمان اجرا، تعداد تخصیصها و آزادسازیهای اشیاء از آخرین زبالهروبی را پیگیری میکند. هنگامی که تعداد تخصیصها منهای تعداد آزادسازیها از threshold0 بیشتر شود، زبالهروبی آغاز میشود. در ابتدا فقط نسل0بررسی میشود. اگر نسل0از زمانی که نسل1بررسی شده است بیش از threshold1 بار بررسی شده باشد، نسل1نیز بررسی میشود. در مورد نسل سوم، اوضاع کمی پیچیدهتر است؛ برای اطلاعات بیشتر جمعآوری قدیمیترین نسل را ببینید.در ساخت نخآزاد (free-threaded build)، افزایش مصرف حافظهی فرایند نیز پیش از اجرای جمعآور بررسی میشود. اگر مصرف حافظه از زمان آخرین جمعآوری ۱۰ درصد افزایش پیدا نکرده باشد و تعداد خالص تخصیصهای شیء از ۴۰ برابر threshold0 فراتر نرفته باشد، جمعآوری اجرا نمیشود.
برای اطلاعات بیشتر، طراحی زبالهرو را ببینید.
تغییر یافته در نسخهی 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قرار گرفتند.برنامهها میتوانند کالبکهای خود را به این فهرست اضافه کنند. موارد استفاده اصلی عبارتند از:
جمعآوری آمار درباره زبالهروبی، مانند تعداد دفعات جمعآوری نسلهای مختلف و مدتزمان جمعآوری.
اجازه دادن به برنامهها برای شناسایی و پاکسازی انواع غیرقابلجمعآوری خودشان، هنگامی که در
garbageظاهر میشوند.اضافه شده در نسخهی 3.3.
ثابتهای زیر برای استفاده با 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).