gc — Gränssnitt för skräpsamlare


Den här modulen ger ett gränssnitt till den valfria skräpsamlaren. Den gör det möjligt att inaktivera uppsamlaren, ställa in uppsamlingsfrekvensen och ange felsökningsalternativ. Den ger också tillgång till onåbara objekt som uppsamlaren har hittat men inte kan frigöra. Eftersom uppsamlaren kompletterar den referensräkning som redan används i Python, kan du inaktivera uppsamlaren om du är säker på att ditt program inte skapar referenscykler. Automatisk insamling kan avaktiveras genom att anropa gc.disable(). För att debugga ett läckande program anropa gc.set_debug(gc.DEBUG_LEAK). Observera att detta inkluderar gc.DEBUG_SAVEALL, vilket gör att skräpinsamlade objekt sparas i gc.garbage för inspektion.

Modulen gc tillhandahåller följande funktioner:

gc.enable()

Aktivera automatisk skräpplockning.

gc.disable()

Avaktivera automatisk skräpplockning.

gc.isenabled()

Returnerar True om automatisk insamling är aktiverad.

gc.collect(generation=2)

Utför en insamling. Det valfria argumentet generation kan vara ett heltal som anger vilken generation som ska samlas in (från 0 till 2). Ett ValueError uppstår om generationsnumret är ogiltigt. Summan av hämtade objekt och ej hämtningsbara objekt returneras.

Om du ringer gc.collect(0) kommer du att utföra en GC-kollektion på den unga generationen.

Om du anropar gc.collect(1) kommer du att utföra en GC-samling på den unga generationen och en ökning av den gamla generationen.

Anrop av gc.collect(2) eller gc.collect() utför en fullständig insamling

De fria listor som upprätthålls för ett antal inbyggda typer rensas när en fullständig samling eller samling av den högsta generationen (2) körs. Det är inte säkert att alla objekt i vissa fria listor blir fria på grund av den speciella implementeringen, i synnerhet float.

Effekten av att anropa gc.collect() medan tolken redan utför en insamling är odefinierad.

Ändrad i version 3.14: generation=1 utför en inkrementering av insamlingen.

gc.set_debug(flags)

Ställ in felsökningsflaggorna för skräpplockning. Felsökningsinformation kommer att skrivas till sys.stderr. Se nedan för en lista över felsökningsflaggor som kan kombineras med bitoperationer för att styra felsökningen.

gc.get_debug()

Returnerar de felsökningsflaggor som för närvarande är inställda.

gc.get_objects(generation=None)

Returnerar en lista över alla objekt som spåras av samlaren, exklusive den returnerade listan. Om generation inte är None, returneras endast objekten enligt följande:

  • 0: Alla objekt i den unga generationen

  • 1: Inga objekt, eftersom det inte finns någon generation 1 (från och med Python 3.14)

  • 2: Alla objekt i den gamla generationen

Ändrad i version 3.8: Ny generation parameter.

Ändrad i version 3.14: Generation 1 är borttagen

Utlöser en auditing event gc.get_objects med argumentet generation.

gc.get_stats()

Returnerar en lista med tre ordböcker per generation som innehåller samlingsstatistik sedan tolken startade. Antalet nycklar kan komma att ändras i framtiden, men för närvarande innehåller varje ordbok följande poster:

  • collections är antalet gånger som denna generation har samlats in;

  • collected är det totala antalet objekt som samlats in under denna generation;

  • uncollectable är det totala antalet objekt som befanns vara omöjliga att samla in (och som därför flyttades till garbage-listan) i denna generation.

Tillagd i version 3.4.

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

Ställ in tröskelvärdena för sophämtning (hämtningsfrekvensen). Om threshold0 sätts till noll avaktiveras insamlingen.

GC klassificerar föremål i två generationer beroende på om de har överlevt en samling eller inte. Nya föremål placeras i den unga generationen. Om ett föremål överlever en insamling flyttas det till den gamla generationen.

För att bestämma när insamlingen ska starta håller insamlaren reda på antalet objektallokeringar och -deallokeringar sedan den senaste insamlingen. När antalet allokeringar minus antalet deallokeringar överstiger tröskelvärde0 startar insamlingen. För varje insamling samlas alla objekt i den unga generationen och en del av den gamla generationen in.

I den fritt trådade versionen kontrolleras även ökningen av processminnesanvändningen innan insamlingsverktyget körs. Om minnesanvändningen inte har ökat med 10% ssedan den senaste insamlingen och nettoantalet objektallokeringar inte har överstigit 40 gånger tröskelvärde0, körs inte insamlingen.

Den andel av den gamla generationen som samlas in är omvänt proportionell mot tröskelvärde1. Ju större threshold1 är, desto långsammare samlas objekt i den gamla generationen in. För standardvärdet 10 skannas 1% of av den gamla generationen under varje insamling.

tröskelvärde2 ignoreras.

Se Garbage collector design för mer information.

Ändrad i version 3.14: tröskelvärde2 ignoreras

gc.get_count()

Returnera den aktuella samlingens antal som en tupel av (count0, count1, count2).

gc.get_threshold()

Returnera de aktuella tröskelvärdena för samlingen som en tupel av (tröskel0, tröskel1, tröskel2).

gc.get_referrers(*objs)

Returnerar listan över objekt som direkt refererar till något av objs. Denna funktion kommer endast att hitta de behållare som stöder garbage collection; extension types som refererar till andra objekt men inte stöder garbage collection kommer inte att hittas.

Observera att objekt som redan har avrefererats, men som lever i cykler och ännu inte har samlats in av skräpsamlaren, kan listas bland de resulterande referenterna. Om du bara vill få fram objekt som lever för närvarande, anropa collect() innan du anropar get_referrers().

Varning

Försiktighet måste iakttas när du använder objekt som returneras av get_referrers() eftersom vissa av dem fortfarande kan vara under konstruktion och därmed i ett tillfälligt ogiltigt tillstånd. Undvik att använda get_referrers() för något annat ändamål än felsökning.

Utlöser en auditing event gc.get_referrers med argumentet objs.

gc.get_referents(*objs)

Returnerar en lista med objekt som direkt refereras till av något av argumenten. De referenser som returneras är de objekt som besöks av argumentens C-nivå tp_traverse-metoder (om sådana finns), och kanske inte alla objekt som faktiskt är direkt nåbara. tp_traverse-metoder stöds endast av objekt som stöder garbage collection, och behöver endast besöka objekt som kan vara inblandade i en cykel. Om t.ex. ett heltal är direkt nåbart från ett argument, kan det hända att detta heltalsobjekt inte finns med i resultatlistan.

Utlöser en auditing event gc.get_referents med argumentet objs.

gc.is_tracked(obj)

Returnerar True om objektet för närvarande spåras av skräpsamlaren, annars False. Som en allmän regel spåras inte instanser av atomära typer och instanser av icke-atomära typer (behållare, användardefinierade objekt …) spåras. Vissa typspecifika optimeringar kan dock finnas för att minska skräpsamlarens fotavtryck för enkla instanser (t.ex. dikter som endast innehåller atomiska nycklar och värden):

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

Tillagd i version 3.1.

gc.is_finalized(obj)

Returnerar True om det angivna objektet har slutförts av skräpsamlaren, False annars.

>>> 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

Tillagd i version 3.9.

gc.freeze()

Frys alla objekt som spåras av skräpsamlaren; flytta dem till en permanent generation och ignorera dem i alla framtida samlingar.

Om en process kommer att fork() utan exec(), kommer undvikande av onödig copy-on-write i barnprocesser att maximera minnesdelning och minska den totala minnesanvändningen. Detta kräver både att man undviker att skapa frigjorda ”hål” i minnessidor i den överordnade processen och att man ser till att GC-samlingar i underordnade processer inte rör gc_refs-räknaren för långlivade objekt som härrör från den överordnade processen. För att åstadkomma båda, anropa gc.disable() tidigt i den överordnade processen, gc.freeze() strax före fork() och gc.enable() tidigt i underordnade processer.

Tillagd i version 3.7.

gc.unfreeze()

Frigör objekten i den permanenta generationen, lägg tillbaka dem i den äldsta generationen.

Tillagd i version 3.7.

gc.get_freeze_count()

Returnera antalet objekt i den permanenta generationen.

Tillagd i version 3.7.

Följande variabler tillhandahålls för skrivskyddad åtkomst (du kan ändra värdena men bör inte binda om dem):

gc.garbage

En lista över objekt som samlaren fann vara oåtkomliga men som inte kunde frigöras (ej insamlingsbara objekt). Från och med Python 3.4 bör denna lista vara tom för det mesta, förutom när man använder instanser av C-tilläggstyper med en icke-NULL tp_del slot.

Om DEBUG_SAVEALL är inställd kommer alla oåtkomliga objekt att läggas till i listan i stället för att frigöras.

Ändrad i version 3.2: Om listan inte är tom vid interpreter shutdown, skickas en ResourceWarning, som är tyst som standard. Om DEBUG_UNCOLLECTABLE är inställt, skrivs dessutom alla objekt som inte kan hämtas ut.

Ändrad i version 3.4: Efter PEP 442, hamnar objekt med en __del__()-metod inte längre i gc.garbage.

gc.callbacks

En lista över callbacks som anropas av garbage collector före och efter insamlingen. Återkallelserna kommer att anropas med två argument, phase och info.

phase kan ha ett av två värden:

”start”: Skräpplockningen ska snart börja.

”stopp”: Skräpplockningen har avslutats.

info är ett dict som ger mer information om återuppringningen. Följande nycklar är för närvarande definierade:

”generation”: Den äldsta generationen som samlas in.

”insamlade”: När fas är ”stop”, antalet objekt som framgångsrikt samlats in.

”ej insamlingsbara”: När fas är ”stop”, antalet objekt som inte kunde samlas in och som placerades i garbage.

Applikationer kan lägga till sina egna callbacks i denna lista. De primära användningsfallen är:

Samla in statistik om garbage collection, t.ex. hur ofta olika generationer samlas in och hur lång tid insamlingen tar.

Tillåter applikationer att identifiera och rensa sina egna typer som inte går att samla in när de visas i garbage.

Tillagd i version 3.3.

Följande konstanter tillhandahålls för användning med set_debug():

gc.DEBUG_STATS

Skriv ut statistik under insamlingen. Denna information kan vara användbar när du ställer in insamlingsfrekvensen.

gc.DEBUG_COLLECTABLE

Skriv ut information om upphittade samlarobjekt.

gc.DEBUG_UNCOLLECTABLE

Skriv ut information om icke insamlingsbara objekt som hittats (objekt som inte kan nås men som inte kan frigöras av insamlaren). Dessa objekt kommer att läggas till i listan garbage.

Ändrad i version 3.2: Skriv även ut innehållet i garbage-listan vid interpreter shutdown, om den inte är tom.

gc.DEBUG_SAVEALL

När den är inställd kommer alla oåtkomliga objekt som hittas att läggas till garbage i stället för att frigöras. Detta kan vara användbart vid felsökning av ett läckande program.

gc.DEBUG_LEAK

De felsökningsflaggor som krävs för att samlaren ska kunna skriva ut information om ett program som läcker (lika med DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_SAVEALL).