参照カウント

このセクションにある関数とマクロは、 Python オブジェクトの参照カウントの管理に使用されます。

Py_ssize_t Py_REFCNT(PyObject *o)

次に属します: Stable ABI (バージョン 3.14 より).

Python オブジェクト o の参照カウントを取得します。

戻り値は、実際に保持されているオブジェクトの参照の数を実際に反映しているとは限らないことに注意してください。例えば、一部のオブジェクトは永続 (immortal) であり、実際の参照の数を反映しない非常に高い参照数を持ちます。したがって、 0 か 1 の値以外では、正確な戻り値に頼らないでください。

オブジェクトの参照カウントを設定するためには、 Py_SET_REFCNT() 関数を使用してください。

注釈

Python の フリースレッドビルド では、戻り値が 1 であるだけでは、ほかのスレッドから o へのアクセスがないものとして安全に扱えるかどうかを判断できません。 その判断には PyUnstable_Object_IsUniquelyReferenced() を使ってください。

PyUnstable_Object_IsUniqueReferencedTemporary() 関数も参照してください。

バージョン 3.10 で変更: Py_REFCNT() は static なインライン関数に変更されました。

バージョン 3.11 で変更: 引数の型は const PyObject* ではなくなりました。

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

This macro is available when compiling for the Stable ABI (バージョン 3.9 より).

オブジェクト o の参照カウントを refcnt に設定します。

フリースレッドな Python ビルド では、 refcnt が UINT32_MAX より大きい場合、オブジェクトは永続 (immortal) となります。

この関数は永続 (immortal) オブジェクトには何もしません。

Added in version 3.9.

バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_INCREF(PyObject *o)

This macro is available when compiling for the Stable ABI.

オブジェクト o への新しい 強参照 を取得し、それが使用中で破棄されてはならないことを示します。

この関数は永続 (immortal) オブジェクトには何もしません。

この関数は通常、借用参照 をその場で 強参照 に変換するために使います。 新しい 強参照 の作成には Py_NewRef() 関数を使えます。

オブジェクトを使い終わったら、Py_DECREF() を呼び出して参照を解放します。

オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XINCREF() を使ってください。

この関数が実際に o を変更するとは限りません。 少なくとも 一部のオブジェクト に対しては、この関数は何もしません。

バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_XINCREF(PyObject *o)

This macro is available when compiling for the Stable ABI.

Py_INCREF() と同様ですが、オブジェクト o は NULL でも構いません。 その場合は何もしません。

Py_XNewRef() も参照してください。

PyObject *Py_NewRef(PyObject *o)

次に属します: Stable ABI (バージョン 3.10 より).

オブジェクトへの新しい 強参照 を作成します。 o に対して Py_INCREF() を呼び出し、オブジェクト o を返します。

強参照 が不要になったら、Py_DECREF() を呼び出して解放してください。

オブジェクト o は NULL であってはいけません。 o が NULL になり得る場合は Py_XNewRef() を使ってください。

例えば:

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

は次のように書けます。

self->attr = Py_NewRef(obj);

Py_INCREF() も参照してください。

Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)

次に属します: Stable ABI (バージョン 3.10 より).

Py_NewRef() と同様ですが、オブジェクト o は NULL でも構いません。

オブジェクト o が NULL の場合、この関数は単に NULL を返します。

Added in version 3.10.

void Py_DECREF(PyObject *o)

This macro is available when compiling for the Stable ABI.

オブジェクト o への 強参照 を解放し、その参照をもう使わないことを示します。

この関数は永続 (immortal) オブジェクトには何もしません。

最後の 強参照 が解放されると (つまり、オブジェクトの参照カウントが 0 になると)、そのオブジェクトの型の解放関数が呼び出されます。 この関数は NULL であってはいけません。

この関数は通常、スコープを抜ける前に 強参照 を削除するために使います。

オブジェクトが NULL であってはいけません。それが NULL ではないと確信が持てないならば、 Py_XDECREF() を使ってください。

この関数が実際に o を変更するとは限りません。 少なくとも 一部のオブジェクト に対しては、この関数は何もしません。

警告

解放関数は任意の Python コードを呼び出すことがあります (例えば __del__() メソッドを持つクラスのインスタンスを解放するとき)。 そのコード内の例外は伝播しませんが、実行されるコードは Python のすべてのグローバル変数に自由にアクセスできます。 このため、グローバル変数から到達できるオブジェクトは、Py_DECREF() を呼び出す前に整合性の取れた状態にしておく必要があります。 例えば、リストからオブジェクトを削除するコードでは、そのオブジェクトへの参照を一時変数にコピーしてからリストのデータ構造を更新し、その後で一時変数に対して Py_DECREF() を呼び出すべきです。

バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_XDECREF(PyObject *o)

This macro is available when compiling for the Stable ABI.

Py_DECREF() と同様ですが、オブジェクト o は NULL でも構いません。 その場合は何もしません。 Py_DECREF() と同じ警告がここにも当てはまります。

void Py_CLEAR(PyObject *o)

This macro is available when compiling for the Stable ABI.

オブジェクト o への 強参照 を解放します。 オブジェクトは NULL でもよく、その場合は何もしません。 それ以外の場合は Py_DECREF() と同じ効果がありますが、引数も NULL に設定します。 このマクロは一時変数を使い、参照を解放する前に引数を NULL に設定するため、渡したオブジェクトについては Py_DECREF() の警告は当てはまりません。

ガベージコレクション中に走査される可能性のあるオブジェクトへの参照を解放するときは、このマクロを使うとよいでしょう。

バージョン 3.12 で変更: マクロの引数を 1 回だけ評価するようになりました。 引数に副作用がある場合も、それが重複して発生することはなくなりました。

void Py_IncRef(PyObject *o)

次に属します: Stable ABI.

オブジェクト o への新しい 強参照 を取得することを示します。 Py_XINCREF() の関数版です。 実行時に Python を動的に組み込むために使えます。

void Py_DecRef(PyObject *o)

次に属します: Stable ABI.

オブジェクト o への 強参照 を解放します。 Py_XDECREF() の関数版です。 実行時に Python を動的に組み込むために使えます。

Py_SETREF(dst, src)

オブジェクト dst への 強参照 を安全に解放し、dst を src に設定するマクロです。

Py_CLEAR() の場合と同様に、「当然」と思える次のコードは致命的な結果を招くことがあります。

Py_DECREF(dst);
dst = src;

安全な書き方は次のとおりです。

Py_SETREF(dst, src);

これにより、dst の古い値への参照を解放する 前に、dst に src が設定されます。 そのため、古いオブジェクトの破棄に伴って実行されるコードが、dst はそのオブジェクトをまだ有効な状態で指していると誤認することを防げます。

Added in version 3.6.

バージョン 3.12 で変更: マクロの引数をそれぞれ 1 回だけ評価するようになりました。 引数に副作用がある場合も、それが重複して発生することはなくなりました。

Py_XSETREF(dst, src)

Py_DECREF() の代わりに Py_XDECREF() を使う Py_SETREF マクロの変種です。

Added in version 3.6.

バージョン 3.12 で変更: マクロの引数をそれぞれ 1 回だけ評価するようになりました。 引数に副作用がある場合も、それが重複して発生することはなくなりました。