\chapter{初期化 (initialization)、終了処理 (finalization)、スレッド 
\label{initialization}}

\begin{cfuncdesc}{void}{Py_Initialize}{}
Python インタプリタを初期化します。Python の埋め込みを行う
アプリケーションでは、他のあらゆる Python/C API を使用するよりも
前にこの関数を呼び出さねばなりません; ただし、
\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
\cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
および \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}
は例外です。
この関数はロード済みモジュールのテーブル (\code{sys.modules})
を初期化\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
し、基盤となるモジュール群、
\module{__builtin__}\refbimodindex{__builtin__},
\module{__main__}\refbimodindex{__main__} および
\module{sys}\refbimodindex{sys} を生成します。
また、モジュール検索パス \indexiii{module}{search}{path} 
(\code{sys.path}) も初期化します。
\code{sys.argv} の設定は行いません; 設定するには、
\cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} を使ってください。
この関数を (\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} を
呼ばずに) 再度呼び出しても何も行いません。
戻り値はありません; 初期化が失敗すれば、それは致命的なエラーです。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{Py_InitializeEx}{int initsigs}
  \var{initsigs}に1を指定すれば\cfunction{Py_Initialize()}と同じ処理を実
  行しますが、Python埋め込みアプリケーションでは\var{initsigs}を0として
  初期化時にシグナルハンドラの登録をスキップすることができます。
  \versionadded{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{Py_IsInitialized}{}
Python インタプリタがすでに初期化済みの場合に真 (非ゼロ) を返し、
そうでない場合には偽 (ゼロ) を返します。\cfunction{Py_Finalize()}
を呼び出すと、次に\cfunction{Py_Initialize()} を呼び出すまで
この関数は偽を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{Py_Finalize}{}
\cfunction{Py_Initialize()} とそれ以後の Python/C API 関数で行った
全ての初期化処理を取り消し、最後の \cfunction{Py_Initialize()} 
呼び出し以後に Python インタプリタが生成した全てのサブインタプリタ 
(sub-interpreter, 下記の \cfunction{Py_NewInterpreter()} を参照) を
消去します。
理想的な状況では、この関数によって Python インタプリタが確保した
メモリは全て解放されます。
この関数を (\cfunction{Py_Initialize()} を呼ばずに) 再度呼び出しても
何も行いません。
戻り値はありません; 終了処理中のエラーは無視されます。

この関数が提供されている理由はいくつかあります。Python の埋め込みを
行っているアプリケーションでは、アプリケーションを再起動することなく
Python を再起動したいことがあります。また、動的ロード可能イブラリ
(あるいは DLL) から Python インタプリタをロードするアプリケーション
では、DLL をアンロードする前に Python が確保したメモリを解放したい
と考えるかもしれません。アプリケーション内で起きているメモリリークを
追跡する際に、開発者は Python が確保したメモリをアプリケーションの
終了前に解放させたいと思う場合もあります。

\strong{バグおよび注意事項:} モジュールやモジュール内のオブジェクト
はランダムな順番で削除されます; このため、他のオブジェクト
(関数オブジェクトも含みます) やモジュールに依存するデストラクタ 
(\method{__del__()} メソッド) が失敗してしまうことがあります。
動的にロードされるようになっている拡張モジュールが Python によって
ロードされていた場合、アンロードされません。Python が確保した
メモリがわずかながら解放されないかもしれません (メモリリークを
発見したら、どうか報告してください)。オブジェクト間の循環参照に
捕捉されているメモリは解放されないことがあります。拡張モジュール
が確保したメモリは解放されないことがあります。拡張モジュールに
よっては、初期化ルーチンを 2 度以上呼び出すと正しく動作
しないことがあります; こうした状況は、\cfunction{Py_Initialize()} 
や\cfunction{Py_Finalize()} を 2 度以上呼び出すと起こり得ます。
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
新しいサブインタプリタ (sub-interpreter) を生成します。
サブインタプリタとは、(ほぼ完全に) 個別に分割された
Python コードの実行環境です。特に、新しいサブインタプリタは、
import されるモジュール全てについて個別のバージョンを持ち、
これには基盤となるモジュール
  \module{__builtin__}\refbimodindex{__builtin__},
  \module{__main__}\refbimodindex{__main__} および
  \module{sys}\refbimodindex{sys} も含まれます。
ロード済みのモジュールからなるテーブル (\code{sys.modules}) 
およびモジュール検索パス (\code{sys.path}) もサブインタプリタ
毎に別個のものになります。新たなサブインタプリタ環境には
\code{sys.argv} 変数がありません。また、サブインタプリタは
新たな標準 I/O ストリーム \code{sys.stdin}, \code{sys.stdout} および
\code{sys.stderr} を持ちます (とはいえ、これらのストリームは
根底にある C ライブラリの同じ \ctype{FILE} 構造体を参照しています)。
  \withsubitem{(in module sys)}{
    \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}

戻り値は、新たなサブインタプリタが生成したスレッド状態 (thread state)
オブジェクトのうち、最初のものを指しています。
このスレッド状態が現在のスレッド状態 (current thread state) になります。
実際のスレッドが生成されるわけではないので注意してください;
下記のスレッド状態に関する議論を参照してください。
新たなインタプリタの生成に失敗すると、\NULL{} を返します;
例外状態はセットされませんが、これは例外状態が現在のスレッド状態に
保存されることになっていて、現在のスレッド状態なるものが
存在しないことがあるからです。 (他の Python/C API 関数のように、
この関数を呼び出す前にはグローバルインタプリタロック
(global interpreter lock) が保持されていなければならず、関数が
処理を戻した際にも保持されたままになります; しかし、
他の Python/C API 関数とは違い、関数から戻ったときの現在のスレッド状態
が関数に入るときと同じとは限らないので注意してください)。

拡張モジュールは以下のような形で (サブ) インタプリタ間で共有
されます: ある特定の拡張モジュールを最初に import すると、
モジュールを通常通りに初期化し、そのモジュールの辞書の
(浅い) コピーをしまい込んでおきます。他の (サブ) インタプリタが
同じ拡張モジュールを import すると、新たなモジュールを初期化し、
先ほどのコピーの内容で辞書の値を埋めます; 拡張モジュールの
\code{init} 関数は呼び出されません。この挙動は、
\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} および
\cfunction{Py_Initialize()}\ttindex{Py_Initialize()} を呼び出して
インタプリタを完全に再初期化した後に拡張モジュールを import した
際の挙動とは異なるので注意してください; 再初期化後に import を
行うと、拡張モジュールの \code{init\var{module}} は再度
\emph{呼び出され} ます。

\strong{バグと注意事項:} サブインタプリタ (とメインインタプリタ)
は同じプロセスの一部分なので、インタプリタ間の絶縁性は完璧では
ありません --- 例えば、\withsubitem{(in module os)}{\ttindex{close()}}
\function{os.close()} のような低レベルのファイル操作を使うと、
(偶然なり故意なりに) 互いのインタプリタ下にある開かれたファイルに
影響を及ぼせてしまいます。
拡張モジュールを (サブ) インタプリタ間で共有する方法のために、
拡張モジュールによっては正しく動作しないかもしれません; 
拡張モジュールが (静的な) グローバル変数を利用している
場合や、拡張モジュールが初期化後に自身のモジュール辞書を操作
する場合には特にそうです。
一つのサブインタプリタで生成されたオブジェクトは他のサブインタプリタ
の名前空間への挿入が可能です; ユーザ定義関数、メソッド、インスタンス
およびクラスをサブインタプリタをサブインタプリタ間で共有しないように
十分注意してください。というのは、これらの共有オブジェクトが
実行した import 文は間違った (サブ) インタプリタのロード済み
モジュール辞書に影響を及ぼす場合があるからです (XXX この問題は
修正が難しいバグで、将来のリリースで解決される予定です)

この機能は PyObjC や ctypes のような、\cfunction{PyGILState_*} API を利用する
タイプの拡張モジュールと相性が悪いことにも注意してください。
(これは、\cfunction{PyGILState_*} 関数の動作特有の問題です)
シンプルなことなら上手くいくかもしれませんが、いつ混乱させる動作をするかわかりません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
指定されたスレッド状態 \var{tstate} で表現される (サブ) インタプリタを
抹消します。\var{tstate} は現在のスレッド状態でなければなりません。
下記のスレッド状態に関する議論を参照してください。関数呼び出しが
戻ったとき、現在のスレッド状態は \NULL になっています。
このインタプリタに関連付けられた全てのスレッド状態は抹消されます。
(この関数を呼び出す前にはグローバルインタプリタロックを保持して
おかねばならず、ロックは関数が戻ったときも保持されています。)
\cfunction{Py_Finalize()}\ttindex{Py_Finalize()} は、その時点で
明示的に抹消されていない全てのサブインタプリタを抹消します。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
この関数を呼び出すなら、最初に
\cfunction{Py_Initialize()}\ttindex{Py_Initialize()} を呼び出す
よりも前に呼び出さねばなりません。この関数はインタプリタに
プログラムの\cfunction{main()}\ttindex{main()} 関数に
指定した\code{argv[0]} 引数の値を教えます。
この引数値は、\cfunction{Py_GetPath()}\ttindex{Py_GetPath()} や、
以下に示すその他の関数が、インタプリタの実行可能形式から
Python ランタイムライブラリへの相対パスを取得するために使われます。
デフォルトの値は\code{'python'} です。引数はゼロ終端された
キャラクタ文字列で、静的な記憶領域に入っていなければならず、
その内容はプログラムの実行中に変更してはなりません。
Python インタプリタ内のコードで、この記憶領域の内容を変更するものは
一切ありません。
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
\cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} で
設定されたプログラム名か、デフォルトのプログラム名を返します。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の
呼び出し側はこの値を変更できません。
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
プラットフォーム非依存のファイル群がインストールされている場所である
\emph{prefix} を返します。この値は
\cfunction{Py_SetProgramName()} でセットされたプログラム名や
いくつかの環境変数をもとに、数々の複雑な規則から導出されます;
例えば、プログラム名が\code{'/usr/local/bin/python'}
の場合、prefix は \code{'/usr/local'} になります。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の
呼び出し側はこの値を変更できません。
この値はトップレベルの \file{Makefile} に指定されている変数
\makevar{prefix} や、ビルド値に \program{configure} スクリプト
に指定した \longprogramopt{prefix} 引数に対応しています。
この値は Python コードからは \code{sys.prefix} として利用できます。
\UNIX{} でも有用です。次に説明する関数も参照してください。
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
プラットフォーム\emph{依存} のファイルがインストールされている場所
である\emph{exec-prefix} を返します。
この値は\cfunction{Py_SetProgramName()} でセットされたプログラム名や
いくつかの環境変数をもとに、数々の複雑な規則から導出されます;
例えば、プログラム名が\code{'/usr/local/bin/python'}
の場合、exec-prefix は \code{'/usr/local'} になります。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の
呼び出し側はこの値を変更できません。
この値はトップレベルの \file{Makefile} に指定されている変数
\makevar{exec_prefix} や、ビルド値に \program{configure} スクリプト
に指定した \longprogramopt{exec-prefix} 引数に対応しています。
この値は Python コードからは \code{sys.exec_prefix} として利用できます。
\UNIX のみで有用です。

背景: プラットフォーム依存のファイル (実行形式や共有ライブラリ) が、
別個のディレクトリツリー内にインストールされている場合、
exec-prefix は prefix と異なります。典型的なインストール形態では、
プラットフォーム非依存のファイルが\file{/usr/local} に収められる一方、
プラットフォーム依存のファイルは\file{/usr/local/plat} サブツリーに
収められます。

概して、プラットフォームとは、ハードウェアとソフトウェアファミリの
組み合わせを指します。例えば、 Solaris 2.x を動作させている Sparc 
マシンは全て同じプラットフォームであるとみなしますが、Solaris 2.x
を動作させている Intel マシンは違うプラットフォームになりますし、
同じ Intel マシンでも Linux を動作させているならまた別の
プラットフォームです。一般的には、同じオペレーティングシステムでも、
メジャーリビジョンの違うものは異なるプラットフォームです。
非 \UNIX{} のオペレーティングシステムの場合は話はまた別です;
非 \UNIX{} のシステムでは、インストール方法はとても異なっていて、
prefix や exec-prefix には意味がなく、空文字列が設定されている
ことがあります。コンパイル済みの Python バイトコードは
プラットフォームに依存しないので注意してください (ただし、
どのバージョンの Python でコンパイルされたかには依存します!)。

システム管理者は、\program{mount} や \program{automount} プログラムを
使って、各プラットフォーム用の\file{/usr/local/plat} を異なった
ファイルシステムに置き、プラットフォーム間で \file{/usr/local} を
共有するための設定方法を知っているはずです。
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
Python 実行可能形式の完全なプログラム名を返します; この値は
デフォルトのモジュール検索パスを (前述の\cfunction{Py_SetProgramName()}
\ttindex{Py_SetProgramName()} で設定された) プログラム名から導出する際に
副作用的に計算されます。
関数が返す文字列ポインタは静的な記憶領域を返します; 関数の
呼び出し側はこの値を変更できません。
この値は Python コードからは \code{sys.executable} として利用できます。
\UNIX のみで有用です。
  \withsubitem{(in module sys)}{\ttindex{executable}}
\end{cfuncdesc}

\begin{cfuncdesc}{char*}{Py_GetPath}{}
  \indexiii{module}{search}{path}
デフォルトモジュール検索パスを返します; パスは (上の
\cfunction{Py_SetProgramName()} で設定された) プログラム名と、
いくつかの環境変数から計算されます。戻り値となる文字列は、
プラットフォーム依存のパスデリミタ文字で分割された一連の
ディレクトリ名からなります。デリミタ文字は \UNIX と Mac OS X では\character{:}、
Windows では\character{;} です。
関数が返す文字列ポインタは静的な記憶領域を返します; 
関数の呼び出し側はこの値を変更できません。
この値は Python コードからはリスト
\code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}} として
利用できます。このリストは、値を修正して将来モジュールをロードする際に
使う検索パスを変更できます。

  % XXX should give the exact rules
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
Python インタプリタのバージョンを返します。バージョンは、

\begin{verbatim}
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
\end{verbatim}

ような形式の文字列です。

第一ワード (最初のスペース文字まで) は、現在の Python のバージョン
です; 最初の三文字は、メジャーバージョンとマイナーバージョン、そして
それを分割しているピリオドです。関数が返す文字列ポインタは静的な
記憶領域を返します; 関数の呼び出し側はこの値を変更できません。
この値は Python コードからは\code{sys.version}として利用できます。
  \withsubitem{(in module sys)}{\ttindex{version}}
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetBuildNumber}{}
このPython実行ファイルが、Subversionのどのリビジョンからビルドされたかを表す
文字列を返します。
リビジョンを混ぜて作られたPythonでは末尾に 'M' をつけるので、
この番号は文字列になっています。
  \versionadded{2.5}
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
現在のプラットフォームのプラットフォーム識別文字列を返します。
\UNIX では、オペレーティングシステムの ``公式の'' 名前を小文字に
変換し、後ろにメジャーリビジョン番号を付けた構成になっています;
例えば Solaris 2.x は、SunOS 5.x, としても知られていますが、
\code{'sunos5'} になります。Mac OS X では \code{'darwin'} です。
Windows では\code{'win'} です。
関数が返す文字列ポインタは静的な
記憶領域を返します; 関数の呼び出し側はこの値を変更できません。
この値は Python コードからは\code{sys.platform}として利用できます。
  \withsubitem{(in module sys)}{\ttindex{platform}}
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
現在の Python バージョンに対する公式の著作権表示文字列、例えば
  \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
を返します。
関数が返す文字列ポインタは静的な
記憶領域を返します; 関数の呼び出し側はこの値を変更できません。
この値は Python コードからは\code{sys.copyright}として利用できます。
  \withsubitem{(in module sys)}{\ttindex{copyright}}
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
現在使っているバージョンの Python をビルドする際に用いたコンパイラ
を示す文字列を、各括弧で囲った文字列を返します。例えば:

\begin{verbatim}
"[GCC 2.7.2.2]"
\end{verbatim}

になります。

関数が返す文字列ポインタは静的な
記憶領域を返します; 関数の呼び出し側はこの値を変更できません。
この値は Python コードからは\code{sys.version} の一部として
取り出せます。
  \withsubitem{(in module sys)}{\ttindex{version}}
\end{cfuncdesc}

\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
現在使っている Python インタプリタインスタンスの、シーケンス番号と
ビルド日時に関する情報を返します。例えば

\begin{verbatim}
"#67, Aug  1 1997, 22:34:28"
\end{verbatim}

になります。

関数が返す文字列ポインタは静的な
記憶領域を返します; 関数の呼び出し側はこの値を変更できません。
この値は Python コードからは\code{sys.version} の一部として
取り出せます。
  \withsubitem{(in module sys)}{\ttindex{version}}
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PySys_SetArgv}{int argc, char **argv}
\var{argc} および \var{argv} に基づいて \code{sys.argv} を設定
します。このパラメタはプログラムの \cfunction{main()}\ttindex{main()}
に渡したパラメタに似ていますが、最初の要素が Python インタプリタ
の宿主となっている実行形式の名前ではなく、実行されるスクリプト名を
参照しなければならない点が違います。実行するスクリプトがない場合、
\var{argv} の最初の要素は空文字列にしてもかまいません。
この関数が \code{sys.argv} の初期化に失敗した場合、致命的
エラー条件を\cfunction{Py_FatalError()}\ttindex{Py_FatalError()}
でシグナルします。
  \withsubitem{(in module sys)}{\ttindex{argv}}
  % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; 
  % check w/ Guido.
\end{cfuncdesc}

% XXX Other PySys thingies (doesn't really belong in this chapter)

\section{スレッド状態 (thread state) とグローバルインタプリタロック (global interpreter lock)
         \label{threads}}

\index{global interpreter lock}
\index{interpreter lock}
\index{lock, interpreter}

Python インタプリタは完全にスレッド安全 (thread safe) ではありません。
マルチスレッドの Python プログラムをサポートするために、グローバルな
ロックが存在していて、現在のスレッドが Python オブジェクトに安全に
アクセスする前に必ずロックを獲得しなければならなくなっています。
ロック機構がなければ、単純な操作でさえ、マルチスレッドプログラムの
実行に問題を引き起こす可能性があります: たとえば、二つのスレッドが
同じオブジェクトの参照カウントを同時にインクリメントすると、
結果的に参照カウントは二回でなく一回だけしかインクリメントされない
かもしれません。

このため、グローバルインタプリタロックを獲得したスレッドだけが
Python オブジェクトを操作したり、 Python/C API 関数を呼び出したり
できるというルールがあります。マルチスレッドの Python プログラムを
サポートするため、インタプリタは定期的に --- デフォルトの設定では
バイトコード 100 命令ごとに (この値は \withsubitem{(in module sys)}
{\ttindex{setcheckinterval()}}\function{sys.setcheckinterval()} で
変更できます) --- ロックを解放したり獲得したりします。
このロックはブロックが起こりうる I/O 操作の付近でも解放・獲得
され、I/O を要求するスレッドが I/O 操作の完了を待つ間、他の
スレッドが動作できるようにしています。

Python インタプリタはスレッドごとに何らかの予約情報を持っておかねば
なりません --- このため、Python は
\ctype{PyThreadState}\ttindex{PyThreadState} と呼ばれるデータ構造
を用います。
とはいえ、グローバル変数はまだ一つだけ残っています: それは現在の
\ctype{PyThreadState}\ttindex{PyThreadState} 構造体を指すポインタです。
ほとんどのスレッドパッケージが ``スレッドごとのグローバルデータ''
を保存する手段を持っている一方で、Python の内部的なプラットフォーム
非依存のスレッド抽象層はこれをサポートしていません。従って、
現在のスレッド状態を明示的に操作するようにしなければなりません。

ほとんどのケースで、このような操作は十分簡単にできます。
グローバルインタプリタロックを操作数ほとんどのコードは、以下のような
単純な構造を持ちます:

\begin{verbatim}
スレッド状態をローカル変数に保存する。
インタプリタロックを解放する。
...ブロックが起きるような何らかの I/O 操作...
インタプリタロックを獲得する。
ローカル変数からスレッド状態を回復する。
\end{verbatim}

このやりかたは非常に一般的なので、作業を単純にするために二つの
マクロが用意されています:

\begin{verbatim}
Py_BEGIN_ALLOW_THREADS
...ブロックが起きるような何らかの I/O 操作...
Py_END_ALLOW_THREADS
\end{verbatim}

\csimplemacro{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS}
マクロは新たなブロック文を開始し、隠しローカル変数を宣言します;
\csimplemacro{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS}
はブロック文を終了します。これらの二つのマクロを使うもうひとつの
利点は、Python をスレッドサポートなしでコンパイルしたとき、
マクロの内容、すなわちスレッド状態の退避とロック操作が空になると
いう点です。

スレッドサポートが有効になっている場合、上記のブロックは
以下のようなコードに展開されます:

\begin{verbatim}
    PyThreadState *_save;

    _save = PyEval_SaveThread();
    ...ブロックが起きるような何らかの I/O 操作...
    PyEval_RestoreThread(_save);
\end{verbatim}

より低水準のプリミティブを使うと、以下のようにしてほぼ同じ効果を
得られます:

\begin{verbatim}
    PyThreadState *_save;

    _save = PyThreadState_Swap(NULL);
    PyEval_ReleaseLock();
    ...ブロックが起きるような何らかの I/O 操作...
    PyEval_AcquireLock();
    PyThreadState_Swap(_save);
\end{verbatim}

上の二つには微妙な違いがあります; とりわけ、
\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} 
はグローバル変数 \cdata{errno}\ttindex{errno} の値を保存しておいて
元に戻す点が異なります。というのは、ロック操作が \cdata{errno} に
何もしないという保証がないからです。また、スレッドサポートが無効化
されている場合、
\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} および
\cfunction{PyEval_RestoreThread()} はロックを操作しません;
この場合、
\cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} および
\cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} は
利用できません。この仕様は、スレッドサポートを無効化してコンパイル
されているインタプリタが、スレッドサポートが有効化された状態で
コンパイルされている動的ロード拡張モジュールをロードできる
ようにするためのものです。

グローバルインタプリタロックは、現在のスレッド状態を指すポインタを
保護するために使われます。ロックを解放してスレッド状態を退避する際、
ロックを解放する前に現在のスレッド状態ポインタを取得しておかなければ
なりません (他のスレッドがすぐさまロックを獲得して、自らの
スレッド状態をグローバル変数に保存してしまうかもしれないからです)。
逆に、ロックを獲得してスレッド状態を復帰する際には、
グローバル変数にスレッド状態ポインタを保存する前にロックを獲得して
おかなければなりません。

なぜここまで詳しく説明しようとするかおわかりでしょうか? それは、
C でスレッドを生成した場合、そのスレッドにはグローバルインタプリタ
ロックがなく、スレッド状態データ構造体もないからです。このような
スレッドが Python/C API を利用するには、まずスレッド状態データ構造体を
生成し、次にロックを獲得し、そしてスレッド状態ポインタを保存すると
いったように、自分自身をブートストラップして生成しなければ
なりません。スレッドが作業を終えたら、スレッド状態ポインタを
リセットして、ロックを解放し、最後にスレッド状態データ構造体を
メモリ解放しなければなりません。

スレッドデータ構造体を生成する際には、インタプリタ状態データ構造体を
指定する必要があります。インタプリタ状態データ構造体は、
インタプリタ内の全てのスレッド間で共有されているグローバルなデータ、
例えばモジュール管理データ (code{sys.modules}) を保持しています。
必要に応じて、新たなインタプリタ状態データ構造体を作成するなり、
Python メインスレッドが使っているインタプリタ状態データ構造体
を共有するなりできます (後者のデータにアクセスするためには、
スレッド状態データ構造体を獲得して、その \member{interp} メンバ
にアクセスしなければなりません; この処理は、Python が作成した
スレッドから行うか、Python を初期化した後で主スレッドから行わねば
なりません)。

インタプリタオブジェクトにアクセスできるという仮定の下では、C の
スレッドから Python を呼び出す際の典型的な常套句は以下のようになります。

バージョン 2.3 からは、上記の事を全て自動で行われて、
スレッドは \cfunction{PyGILState_*()} の恩恵に預かることができます。
C のスレッドから Python を呼び出す典型的な方法は以下のとおりです。

\begin{verbatim}
    PyGILState_STATE gstate;
    gstate = PyGILState_Ensure();

    /* Perform Python actions here.  */
    result = CallSomeFunction();
    /* evaluate result */

    /* Release the thread. No Python API allowed beyond this point. */
    PyGILState_Release(gstate);
\end{verbatim}

\cfunction{PyGILState_*()}関数は、(\cfunction{Py_Initialize()}によって自動的に作られる)
グローバルインタプリタ一つだけが存在すると仮定する事に気をつけて下さい。
Python は (\cfunction{Py_NewInterpreter()}を使って) 追加のインタプリタを作成できることに
変わりはありませんが、複数インタプリタと \cfunction{PyGILState_*()} API を混ぜて
使うことはサポートされていません。

\begin{ctypedesc}{PyInterpreterState}
このデータ構造体は、協調動作する多数のスレッド間で共有されている
状態 (state) を表現します。同じインタプリタに属するスレッドは
モジュール管理情報やその他いくつかの内部的な情報を共有しています。
この構造体には公開 (public) のメンバはありません。

異なるインタプリタに属するスレッド間では、利用可能なメモリ、
開かれているファイルデスクリプタなどといったプロセス状態を除き、
初期状態では何も共有されていません。グローバルインタプリタロック
もまた、スレッドがどのインタプリタに属しているかに関わらず
すべてのスレッドで共有されています。
\end{ctypedesc}

\begin{ctypedesc}{PyThreadState}
単一のスレッドの状態を表現する表現するデータ構造体です。
データメンバ \ctype{PyInterpreterState *}\member{interp}
だけが公開されていて、スレッドのインタプリタ状態を指すポインタに
なっています。
\end{ctypedesc}

\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
グローバルインタプリタロックを初期化し、獲得します。
この関数は、主スレッドが第二のスレッドを生成する以前や、
  \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} や
  \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}
といった他のスレッド操作に入るよりも前に呼び出されるようにして
おかなければなりません。

二度目に呼び出すと何も行いません。この関数を
\cfunction{Py_Initialize()}\ttindex{Py_Initialize()} の前に呼び出しても
安全です。

主スレッドしか存在しないのであれば、ロック操作は必要ありません。
これはよくある状況ですし (ほとんどの Python プログラムはスレッドを
使いません)、ロック操作はインタプリタをごくわずかに低速化します。
従って、初期状態ではロックは生成されません。ロックを使わない状況は、
すでにロックを獲得している状況と同じです: 単一のスレッドしか
なければ、オブジェクトへのアクセスは全て安全です。従って、
この関数がロックを初期化すると、同時にロックを獲得するようになって
います。Python の \module{thread}\refbimodindex{thread} モジュールは、
新たなスレッドを作成する前に、ロックが存在するか、あるいはまだ
作成されていないかを調べ、\cfunction{PyEval_InitThreads()} を
呼び出します。この関数から処理が戻った場合、ロックが作成作成され、呼び出
し元スレッドがそのロックを獲得している事が保証されています。

どのスレッドが現在グローバルインタプリタロックを (存在する場合) 
持っているか分からない時にこの関数を使うのは安全では
\strong{ありません} 。

この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyEval_ThreadsInitialized}{}
\cfunction{PyEval_InitThreads()}をすでに呼び出している場合は真 (非ゼロ)
を返します。この関数は、ロックを獲得せずに呼び出すことができますので、シ
ングルスレッドで実行している場合にはロック関連のAPI呼び出しを避けるため
に使うことができます。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\versionadded{2.4}
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
グローバルインタプリタロックを獲得します。
ロックは前もって作成されていなければなりません。
この関数を呼び出したスレッドがすでにロックを獲得している場合、
デッドロックに陥ります。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
グローバルインタプリタロックを解放します。
ロックは前もって作成されていなければなりません。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
グローバルインタプリタロックを獲得し、現在のスレッド状態を
\var{tstate} に設定します。\var{tstate} は \NULL であっては
なりません。ロックはあらかじめ作成されていなければなりません。
この関数を呼び出したスレッドがすでにロックを獲得している場合、
デッドロックに陥ります。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
現在のスレッド状態をリセットして \NULL{} にし、グローバルインタプリタ
ロックを解放します。ロックはあらかじめ作成されていなければならず、
かつ現在のスレッドが保持していなければなりません。\var{tstate} は
\NULL であってはなりませんが、その値が現在のスレッド状態を
表現しているかどうかを調べるためにだけ使われます --- もしそうで
なければ、致命的エラーが報告されます。
この関数はコンパイル時にスレッドサポートを無効化すると利用できません。
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
(インタプリタロックが生成されていて、スレッドサポートが有効の
場合) インタプリタロックを解放して、スレッド状態を \NULL にし、
以前のスレッド状態 (\NULL にはなりません) を返します。
ロックがすでに生成されている場合、現在のスレッドがロックを獲得
していなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
(インタプリタロックが生成されていて、スレッドサポートが有効の
場合) インタプリタロックを獲得して、現在のスレッド状態を
\var{tstate} に設定します。\var{tstate} は \NULL であっては
なりません。
この関数を呼び出したスレッドがすでにロックを獲得している場合、
デッドロックに陥ります。
(この関数はコンパイル時にスレッドサポートを無効化すると利用できません。)
\end{cfuncdesc}

以下のマクロは、通常末尾にセミコロンを付けずに使います;
Python ソース配布物内の使用例を見てください。

\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
このマクロを展開すると
  \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}
になります。
マクロに開き波括弧が入っていることに注意してください; この波括弧は
後で \csimplemacro{Py_END_ALLOW_THREADS} マクロと対応させなければ
なりません。
マクロについての詳しい議論は上記を参照してください。
コンパイル時にスレッドサポートが無効化されていると何も行いません。
\end{csimplemacrodesc}

\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
このマクロを展開すると
\samp{PyEval_RestoreThread(_save); \}}
になります。
マクロに開き波括弧が入っていることに注意してください; この波括弧は
事前の \csimplemacro{Py_BEGIN_ALLOW_THREADS} マクロと対応して
いなければなりません。
マクロについての詳しい議論は上記を参照してください。
コンパイル時にスレッドサポートが無効化されていると何も行いません。
\end{csimplemacrodesc}

\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
このマクロを展開すると
\samp{PyEval_RestoreThread(_save);}
になります: 閉じ波括弧のない\csimplemacro{Py_END_ALLOW_THREADS}
と同じです。
コンパイル時にスレッドサポートが無効化されていると何も行いません。
\end{csimplemacrodesc}

\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
このマクロを展開すると
\samp{_save = PyEval_SaveThread();}
になります: 閉じ波括弧のない\csimplemacro{Py_BEGIN_ALLOW_THREADS}
と同じです。
コンパイル時にスレッドサポートが無効化されていると何も行いません。
\end{csimplemacrodesc}

以下の全ての関数はコンパイル時にスレッドサポートが有効になっている
時だけ利用でき、呼び出すのはインタプリタロックがすでに作成されている
場合だけにしなくてはなりません。

\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
新しいインタプリタ状態オブジェクトを生成します。
インタプリタロックを保持しておく必要はありませんが、この関数を次々に
呼び出す必要がある場合には保持しておいたほうがよいでしょう。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
インタプリタ状態オブジェクト内の全ての情報をリセットします。
インタプリタロックを保持していなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
インタプリタ状態オブジェクトを破壊します。
インタプリタロックを保持しておく必要はありません。
インタプリタ状態は\cfunction{PyInterpreterState_Clear()} であらかじめ
リセットしておかなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp}
指定したインタプリタオブジェクトに属する新たなスレッド状態オブジェクトを
生成します。
インタプリタロックを保持しておく必要はありませんが、この関数を次々に
呼び出す必要がある場合には保持しておいたほうがよいでしょう。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
スレッド状態オブジェクト内の全ての情報をリセットします。
インタプリタロックを保持していなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
スレッド状態オブジェクトを破壊します。
インタプリタロックを保持していなければなりません。
スレッド状態は\cfunction{PyThreadState_Clear()} であらかじめ
リセットしておかなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
現在のスレッド状態を返します。
インタプリタロックを保持していなければなりません。
現在のスレッド状態が \NULL なら、(呼び出し側が \NULL チェックを
しなくてすむように) この関数は致命的エラーを起こすようになっています。
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
現在のスレッド状態を \var{tstate} に指定したスレッド状態と入れ変えます。
\var{tstate} は\NULL であってはなりません。
インタプリタロックを保持していなければなりません。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
拡張モジュールがスレッド固有の状態情報を保存できるような辞書を返します。
各々の拡張モジュールが辞書に状態情報を保存するためには唯一のキーを
使わねばなりません。
現在のスレッド状態がない時にこの関数を呼び出してもかまいません。
この関数が \NULL を返す場合、例外はまったく送出されず、呼び出し側は
現在のスレッド状態が利用できないと考えねばなりません。
  \versionchanged[以前は、現在のスレッドがアクティブなときのみ呼び出せる
ようになっており、 \NULL{} は例外が送出されたことを意味していました]{2.3}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyThreadState_SetAsyncExc}{long id, PyObject *exc}
スレッド内で非同期的に例外を送出します。
\var{id} 引数はターゲットとなるスレッドのスレッド id です;
\var{exc} は送出する例外オブジェクトです。
この関数は \var{exc} に対する参照を一切盗み取りません。
素朴な間違いを防ぐため、この関数を呼び出すには独自に C 拡張モジュール
を書かねばなりません。
グローバルインタプリタロックを保持した状態で呼び出さなければなりません。

変更を受けたスレッド状態の数を返します; これは普通は1ですが、スレッドidが
見つからなかった場合は0になります。
もし \var{exc} が \constant{NULL} であれば、そのスレッドで保留されている
例外があればクリアします。
この関数自体は例外を送出しません。
  \versionadded{2.3}
\end{cfuncdesc}

\begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
Pythonの状態やスレッドロックに関わらず、実行中スレッドでPython C APIの呼
び出しが可能となるようにします。この関数はスレッド内で何度でも呼び出すこ
とができますが、必ず全ての呼び出しに対応して
\cfunction{PyGILState_Release()}を呼び出す必要があります。

通常、\cfunction{PyGILState_Ensure()}呼び出しと
\cfunction{PyGILState_Release()}呼び出しの間でこれ以外のスレッド関連API
を使用することができますが、Release()の前にスレッド状態は復元されていな
ければなりません。通常の\csimplemacro{Py_BEGIN_ALLOW_THREADS}マクロと
\csimplemacro{Py_END_ALLOW_THREADS}も使用することができます。

戻り値は\cfunction{PyGILState_Acquire()}呼び出し時のスレッド状態を隠蔽し
た"ハンドル"で、\cfunction{PyGILState_Release()}に渡してPythonを同じ状態
に保たなければなりません。再起呼び出しも可能ですが、ハンドルを共有するこ
とは\emph{できません} - それぞれの\cfunction{PyGILState_Ensure}呼び出し
でハンドルを保存し、対応する\cfunction{PyGILState_Release}呼び出しで渡し
てください。

関数から復帰したとき、実行中のスレッドはGILを所有しています。処理の失敗
は致命的なエラーです。

\versionadded{2.3}
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyGILState_Release}{PyGILState_STATE}
獲得したすべてのリソースを開放します。この関数を呼び出すと、Pythonの状態
は対応する\cfunction{PyGILState_Ensure}を呼び出す前と同じとなります。(通
常、この状態は呼び出し元でははわかりませんので、GILState APIを利用するよ
うにしてください。）

\cfunction{PyGILState_Ensure()}を呼び出す場合は、必ず同一スレッド内で対
応する\cfunction{PyGILState_Release()}を呼び出してください。
\versionadded{2.3}
\end{cfuncdesc}


\section{プロファイルとトレース (profiling and tracing) \label{profiling}}

\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

Python インタプリタは、プロファイル: 分析 (profile) や実行の
トレース: 追跡 (trace) といった機能を組み込むために低水準の
サポートを提供しています。このサポートは、プロファイルや
デバッグ、適用範囲分析 (coverage analysis) ツールなどに使われます。

Python 2.2 になってから、この機能の実装は実質的に作り直され、
C から呼び出すためのインタフェースが追加されました。
この C インタフェースは、プロファイルやトレース作業時に、
Python レベルの呼び出し可能オブジェクトが呼び出されることによる
オーバヘッドを避け、直接 C 関数呼び出しが行えるようにしています。
プロファイルやトレース機能の本質的な特性は変わっていません;
インタフェースではとレース関数をスレッドごとにインストールでき、
トレース関数に報告される基本イベント (basic event) は以前の
バージョンにおいて Python レベルのトレース関数で報告されていた
ものと同じです。

\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
                                PyFrameObject *frame, int what,
                                PyObject *arg)}
\cfunction{PyEval_SetProfile()} および \cfunction{PyEval_SetTrace()}
を使って登録できるトレース関数の形式です。最初のパラメタは
オブジェクトで、登録関数に \var{obj} として渡されます。
\var{frame} はイベントが属している実行フレームオブジェクトで、
\var{what} は定数 \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPTION},
\constant{PyTrace_LINE}, \constant{PyTrace_RETURN}, \constant{PyTrace_C_CALL},
\constant{PyTrace_C_EXCEPTION}, あるいは\constant{PyTrace_C_RETURN}
のいずれかで、\var{arg} は \var{what} の値によって以下のように
異なります:

  \begin{tableii}{l|l}{constant}{\var{what} の値}{\var{arg} の意味}
    \lineii{PyTrace_CALL}{常に \NULL です。}
    \lineii{PyTrace_EXCEPTION}{\function{sys.exc_info()} の返す例外情報です。}
    \lineii{PyTrace_LINE}{常に \NULL です。}
    \lineii{PyTrace_RETURN}{呼び出し側に返される予定の値です。}
    \lineii{PyTrace_C_CALL}{呼び出している関数の名前です。}
    \lineii{PyTrace_C_EXCEPTION}{常に \NULL です。}
    \lineii{PyTrace_C_RETURN}{常に \NULL です。}
  \end{tableii}
\end{ctypedesc}

\begin{cvardesc}{int}{PyTrace_CALL}
関数やメソッドが新たに呼び出されたり、ジェネレータが新たなエントリの
処理に入ったことを報告する際の、\ctype{Py_tracefunc} の\var{what} の
値です。イテレータやジェネレータ関数の生成は、対応するフレーム内の
Python バイトコードに制御の委譲 (control transfer) が起こらない
ため報告されないので注意してください。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_EXCEPTION}
例外が送出された際の\ctype{Py_tracefunc} の\var{what} の値です。
現在実行されているフレームで例外がセットされ、何らかのバイトコードが
処理された後に、\var{what} にこの値がセットされた状態でコールバック
関数が呼び出されます。

この結果、例外の伝播によって Python が呼び出しスタックを逆戻りする
際に、各フレームから処理が戻るごとにコールバック関数が呼び出されます。
トレース関数だけがこれらのイベントを受け取ります; プロファイラは
この種のイベントを必要としません。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_LINE}
行番号イベントを報告するときに (プロファイル関数ではなく)
トレース関数の\var{what} パラメタとして渡す値です。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_RETURN}
関数呼び出しが例外の伝播なしに返るときに
\ctype{Py_tracefunc} 関数の\var{what} パラメタとして渡す値です。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_C_CALL}
C関数を呼び出す直前に
\ctype{Py_tracefunc} 関数の\var{what} パラメタとして渡す値です。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_C_EXCEPTION}
C関数が例外を送出したときに
\ctype{Py_tracefunc} 関数の\var{what} パラメタとして渡す値です。
\end{cvardesc}

\begin{cvardesc}{int}{PyTrace_C_RETURN}
C関数から戻るときに
\ctype{Py_tracefunc} 関数の\var{what} パラメタとして渡す値です。
\end{cvardesc}

\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
プロファイル関数を \var{func} に設定します。\var{obj} パラメタは
関数の第一パラメタとして渡され、何らかの Python オブジェクトかまたは
\NULL になります。プロファイル関数がスレッド状態を維持する必要が
あるなら、各々のスレッドに異なる \var{obj} を使うことで、状態を
記憶しておく便利でスレッドセーフな場所を提供できます。プロファイル
関数は、モニタされているイベントのうち、行番号イベントを除く全ての
イベントに対して呼び出されます。
\end{cfuncdesc}

\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
トレース関数を \var{func} にセットします。
\cfunction{PyEval_SetProfile()} に似ていますが、トレース関数は
行番号イベントを受け取る点が違います。
\end{cfuncdesc}


\section{高度なデバッガサポート (advanced debugger support) \label{advanced-debugging}}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

以下の関数は高度なデバッグツールでの使用のためだけのものです。

\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
インタプリタ状態オブジェクトからなるリストのうち、先頭にあるもの
を返します。
  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
インタプリタ状態オブジェクトからなるリストのうち、\var{interp} の
次にあるものを返します。
  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
インタプリタ \var{interp} に関連付けられているスレッドからなるリストの
うち、先頭にある \ctype{PyThreadState} オブジェクトを返します。
  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
\var{tstate} と同じ\ctype{PyInterpreterState} オブジェクトに属している
スレッド状態オブジェクトのうち、\var{tstate} の次にあるものを返します。
  \versionadded{2.2}
\end{cfuncdesc}
