Referensräkning

Funktionerna och makron i det här avsnittet används för att hantera referensantal för Python-objekt.

Py_ssize_t Py_REFCNT(PyObject *o)

En del av Stabil ABI sedan version 3.14.

Hämta referensantalet för Python-objektet o.

Observera att det returnerade värdet kanske inte återspeglar hur många referenser till objektet som faktiskt finns. Vissa objekt är t.ex. immortal och har ett mycket högt refcount som inte återspeglar det faktiska antalet referenser. Förlita dig därför inte på att det returnerade värdet är korrekt, annat än ett värde på 0 eller 1.

Använd funktionen Py_SET_REFCNT() för att ställa in ett objekts referensantal.

Anteckning

I free threaded -versioner av Python räcker det inte att returnera 1 för att avgöra om det är säkert att behandla o som om det inte är tillgängligt för andra trådar. Använd istället PyUnstable_Object_IsUniquelyReferenced() för detta.

Se även funktionen PyUnstable_Object_IsUniqueReferencedTemporary().

Ändrad i version 3.10: Py_REFCNT() ändras till en inline statisk funktion.

Ändrad i version 3.11: Parametertypen är inte längre const PyObject*.

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

Ställ in objektets o referensräknare till refcnt.

På Python build with Free Threading, om refcnt är större än UINT32_MAX, görs objektet immortal.

Denna funktion har ingen effekt på immortal-objekt.

Tillagd i version 3.9.

Ändrad i version 3.12: Odödliga föremål ändras inte.

void Py_INCREF(PyObject *o)

Ange att du tar en ny strong reference till objekt o, vilket indikerar att det används och inte bör förstöras.

Denna funktion har ingen effekt på immortal-objekt.

Denna funktion används vanligtvis för att konvertera en lånad referens till en strong reference på plats. Funktionen Py_NewRef() kan användas för att skapa en ny strong reference.

När du är klar med att använda objektet, släpp det genom att anropa Py_DECREF().

Objektet får inte vara NULL; om du inte är säker på att det inte är NULL, använd Py_XINCREF().

Förvänta dig inte att den här funktionen faktiskt modifierar o på något sätt. För åtminstone vissa objekt har den här funktionen ingen effekt.

Ändrad i version 3.12: Odödliga föremål ändras inte.

void Py_XINCREF(PyObject *o)

Liknar Py_INCREF(), men objektet o kan vara NULL, i vilket fall detta inte har någon effekt.

Se även Py_XNewRef().

PyObject *Py_NewRef(PyObject *o)

En del av Stabil ABI sedan version 3.10.

Skapa en ny strong reference till ett objekt: anropa Py_INCREF() på o och returnera objektet o.

När strong reference inte längre behövs, skall Py_DECREF() anropas för att frigöra referensen.

Objektet o får inte vara NULL; använd Py_XNewRef() om o kan vara NULL.

Till exempel:

Py_INCREF(obj);
self->attr = obj;

kan skrivas som:

self->attr = Py_NewRef(obj);

Se även Py_INCREF().

Tillagd i version 3.10.

PyObject *Py_XNewRef(PyObject *o)

En del av Stabil ABI sedan version 3.10.

Liknar Py_NewRef(), men objektet o kan vara NULL.

Om objektet o är NULL returnerar funktionen bara NULL.

Tillagd i version 3.10.

void Py_DECREF(PyObject *o)

Frigör en strong reference till objekt o, vilket indikerar att referensen inte längre används.

Denna funktion har ingen effekt på immortal-objekt.

När den sista strong reference har släppts (d.v.s. objektets referensantal når 0), anropas objekttypens deallokeringsfunktion (som inte får vara NULL).

Denna funktion används vanligtvis för att ta bort en strong reference innan den lämnar sitt scope.

Objektet får inte vara NULL; om du inte är säker på att det inte är NULL, använd Py_XDECREF().

Förvänta dig inte att den här funktionen faktiskt modifierar o på något sätt. För åtminstone vissa objekt har den här funktionen ingen effekt.

Varning

Funktionen deallocation kan orsaka att godtycklig Python-kod anropas (t.ex. när en klassinstans med en __del__()-metod deallokeras). Undantag i sådan kod sprids inte, men den exekverade koden har fri tillgång till alla Pythons globala variabler. Detta innebär att alla objekt som kan nås från en global variabel bör vara i ett konsekvent tillstånd innan Py_DECREF() anropas. Till exempel bör kod för att ta bort ett objekt från en lista kopiera en referens till det borttagna objektet i en temporär variabel, uppdatera listans datastruktur och sedan anropa Py_DECREF() för den temporära variabeln.

Ändrad i version 3.12: Odödliga föremål ändras inte.

void Py_XDECREF(PyObject *o)

Liknar Py_DECREF(), men objektet o kan vara NULL, i vilket fall detta inte har någon effekt. Samma varning som för Py_DECREF() gäller även här.

void Py_CLEAR(PyObject *o)

Frigör en strong reference för objektet o. Objektet kan vara NULL, i vilket fall makrot inte har någon effekt; i annat fall är effekten densamma som för Py_DECREF(), förutom att argumentet också sätts till NULL. Varningen för Py_DECREF() gäller inte med avseende på det objekt som skickas eftersom makrot försiktigt använder en temporär variabel och sätter argumentet till NULL innan referensen släpps.

Det är en god idé att använda detta makro när man släpper en referens till ett objekt som kan komma att genomkorsas under garbage collection.

Ändrad i version 3.12: Makroargumentet utvärderas nu bara en gång. Om argumentet har bieffekter dupliceras dessa inte längre.

void Py_IncRef(PyObject *o)

En del av Stabil ABI.

Indikerar att en ny strong reference tas till objekt o. En funktionsversion av Py_XINCREF(). Den kan användas för dynamisk inbäddning av Python under körtid.

void Py_DecRef(PyObject *o)

En del av Stabil ABI.

Frigör en strong reference till objekt o. En funktionsversion av Py_XDECREF(). Den kan användas för dynamisk inbäddning av Python under körtid.

Py_SETREF(dst, src)

Makro som på ett säkert sätt släpper en strong reference till objektet dst och sätter dst till src.

Som i fallet med Py_CLEAR(), kan ”den uppenbara” koden vara dödlig:

Py_DECREF(dst);
dst = src;

Det säkra sättet är:

Py_SETREF(dst, src);

Det gör att dst sätts till src innan referensen till det gamla värdet på dst släpps, så att all kod som triggas som en bieffekt av att dst rivs inte längre tror att dst pekar på ett giltigt objekt.

Tillagd i version 3.6.

Ändrad i version 3.12: Makroargumenten utvärderas nu bara en gång. Om ett argument har bieffekter dupliceras dessa inte längre.

Py_XSETREF(dst, src)

Variant av makrot Py_SETREF som använder Py_XDECREF() istället för Py_DECREF().

Tillagd i version 3.6.

Ändrad i version 3.12: Makroargumenten utvärderas nu bara en gång. Om ett argument har bieffekter dupliceras dessa inte längre.