弱参照オブジェクト
******************

Python は *弱参照* を第一級オブジェクト (first-class object) としてサ
ポートします。弱参照を直接実装する二種類の固有のオブジェクト型がありま
す。第一は単純な参照オブジェクトで、第二はオリジナルのオブジェクトに対
して可能な限りプロキシとして振舞うオブジェクトです。

int PyWeakref_Check(PyObject *ob)

   "ob" が弱参照オブジェクトまたはプロキシオブジェクトの場合に非ゼロを
   返します。 この関数は常に成功します。

int PyWeakref_CheckRef(PyObject *ob)

   "ob" が弱参照型またはそのサブクラスのインスタンスの場合に非ゼロを返
   します。 この関数は常に成功します。

int PyWeakref_CheckRefExact(PyObject *ob)

   "ob" が弱参照型のインスタンスであり、サブクラスのインスタンスではな
   い場合に非ゼロを返します。 この関数は常に成功します。

int PyWeakref_CheckProxy(PyObject *ob)

   "ob" がプロキシオブジェクトの場合に非ゼロを返します。 この関数は常
   に成功します。

PyObject *PyWeakref_NewRef(PyObject *ob, PyObject *callback)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   オブジェクト "ob" に対する弱参照オブジェクトを返します。 常に新しい
   参照を返しますが、新しいオブジェクトが作成されるとは限りません。 既
   存の弱参照オブジェクトを返す場合があります。 第 2 引数 "callback"
   には、"ob" がガベージコレクションで回収されたときに通知を受け取る呼
   び出し可能オブジェクトを指定できます。 このオブジェクトは、弱参照オ
   ブジェクト自身を唯一の引数として受け取る必要があります。 "callback"
   は "None" または "NULL" でも構いません。 "ob" が弱参照を作成できる
   オブジェクトでない場合は "TypeError" を送出して "NULL" を返します。

   参考:

     "ob" が弱参照を作成できるオブジェクトかどうかを調べるには
     "PyType_SUPPORTS_WEAKREFS()" を参照してください。

PyObject *PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   Return a weak reference proxy object for the object *ob*.  This
   will always return a new reference, but is not guaranteed to create
   a new object; an existing proxy object may be returned.  The second
   parameter, *callback*, can be a callable object that receives
   notification when *ob* is garbage collected; it should accept a
   single parameter, which will be the weak reference object itself.
   *callback* may also be "None" or "NULL".  If *ob* weakly
   referenceable object, this will raise "TypeError" and return
   "NULL".

   参考:

     "ob" が弱参照を作成できるオブジェクトかどうかを調べるには
     "PyType_SUPPORTS_WEAKREFS()" を参照してください。

int PyWeakref_GetRef(PyObject *ref, PyObject **pobj)
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   弱参照 "ref" から参照先のオブジェクトへの *強参照* を取得し、
   "*pobj" に格納します。

   * 成功した場合は、参照先のオブジェクトへの新しい *強参照* を
     "*pobj" に設定し、1 を返します。

   * 参照先が消滅している場合は、"*pobj" を "NULL" に設定し、0 を返し
     ます。

   * エラーの場合は例外を送出し、-1 を返します。

   Added in version 3.13.

int PyWeakref_IsDead(PyObject *ref)

   弱参照 "ref" の参照先が消滅しているかどうかを調べます。 参照先が消
   滅していれば 1、生存していれば 0 を返します。 "ref" が弱参照オブジ
   ェクトでなければ、エラーを設定して -1 を返します。

   Added in version 3.14.

void PyObject_ClearWeakRefs(PyObject *object)
    * 次に属します: Stable ABI.*

   この関数は、弱参照をクリアするために "tp_dealloc" ハンドラから呼び
   出されます。

   "object" への弱参照を順に調べ、コールバックを持つものについてはその
   コールバックを呼び出します。 すべてのコールバックの呼び出しを試みた
   後で戻ります。

PyObject **PyObject_GET_WEAKREFS_LISTPTR(PyObject *object)

   "object" への弱参照を保持する内部のリンクリストへのポインタを返しま
   す。 "object" は弱参照をサポートしている必要があり、"NULL" であって
   はいけません。

   この関数は内部での使用のみを目的としています。 返されたポインタを通
   じて弱参照リストにアクセスしたり、変更したりしないでください。

   バージョン 3.15.2 で ソフト非推奨 <Soft deprecated>.

void PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *object)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   コールバックを呼び出さずに "object" への弱参照をクリアします。

   この関数は、ファイナライザ (つまり "__del__()") を持つ型の
   "tp_dealloc" ハンドラから呼び出されます。 このようなオブジェクトの
   ハンドラは、まず "PyObject_ClearWeakRefs()" を呼び出して弱参照をク
   リアし、そのコールバックを呼び出します。 次にファイナライザを呼び出
   し、最後にこの関数を呼び出してファイナライザが作成した可能性のある
   弱参照をクリアします。

   ほとんどの場合、弱参照のクリアにはこの関数よりも
   "PyObject_ClearWeakRefs()" を使う方が適切です。

   Added in version 3.13.
