perf map のサポート
*******************

対応するプラットフォーム (Linux と macOS) では、ランタイムは *perf map
ファイル* を使って Python 関数を外部のプロファイリングツール (例えば
perf や samply) に認識させることができます。 実行中のプロセスは "/tmp"
ディレクトリにファイルを作成でき、そのファイルのエントリーによって実行
可能コードの領域と名前を対応づけられます。 このインターフェースについ
ては Linux Perf ツールのドキュメント に記載されています。

Python では、実行中に機械語コードを生成するライブラリや機能が、これら
の補助 API を利用できます。

Note that holding an *attached thread state* is not required for these
APIs.

int PyUnstable_PerfMapState_Init(void)

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

   "/tmp/perf-$pid.map" ファイルがまだ開かれていなければ開き、ファイル
   への書き込みをスレッドセーフにするためのロックを作成します
   ("PyUnstable_WritePerfMapEntry()" を通じて書き込む必要があります)。
   通常、この関数を明示的に呼び出す必要はありません。
   "PyUnstable_WritePerfMapEntry()" を使うだけで、最初の呼び出し時に状
   態が初期化されます。

   成功すると "0"、perf map ファイルの作成またはオープンに失敗すると
   "-1"、ロックの作成に失敗すると "-2" を返します。 失敗の原因の詳細は
   "errno" を確認してください。

int PyUnstable_WritePerfMapEntry(const void *code_addr, size_t code_size, const char *entry_name)

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

   "/tmp/perf-$pid.map" ファイルにエントリーを 1 つ書き込みます。 この
   関数はスレッドセーフです。 エントリーの例を示します。

      # アドレス     サイズ  名前
      7f3529fcf759 b     py::bar:/run/t.py

   perf map ファイルがまだ開かれていなければ、エントリーを書き込む前に
   "PyUnstable_PerfMapState_Init()" を呼び出します。 成功すると "0"、
   失敗すると "PyUnstable_PerfMapState_Init()" と同じエラーコードを返
   します。

void PyUnstable_PerfMapState_Fini(void)

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

   "PyUnstable_PerfMapState_Init()" が開いた perf map ファイルを閉じま
   す。 インタープリタの終了時にランタイム自身がこの関数を呼び出します
   。 通常、fork などの特定の状況に対処する場合を除き、この関数を明示
   的に呼び出す必要はありません。

int PyUnstable_CopyPerfMapFile(const char *parent_filename)

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

   "/tmp/perf-$pid.map" ファイルを開き、*parent_filename* の内容を追記
   します。

   This function is available on all platforms but only generates
   output on platforms that support perf maps (currently only Linux).
   On other platforms, it does nothing.

   Added in version 3.13.

int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)

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

   現在の perf トランポリンを使って、指定されたコードオブジェクトをコ
   ンパイルします。

   The "current" trampoline is the one set by the runtime or the most
   recent "PyUnstable_PerfTrampoline_SetPersistAfterFork()" call.

   If no trampoline is set, falls back to normal compilation (no perf
   map entry).

   パラメータ:
      * **code** -- コンパイルするコードオブジェクト。

   戻り値:
      0 on success, -1 on failure.

   Added in version 3.13.

int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)

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

   fork 後も perf トランポリンを保持するかどうかを設定します。

   * "enable" が真 (ゼロ以外) の場合、fork 後も perf map ファイルは開
     かれた有効な状態を保ちます。 子プロセスは既存のすべての perf map
     エントリーを引き継ぎます。

   * "enable" が偽 (ゼロ) の場合、fork 後に perf map を閉じます。 子プ
     ロセスの perf map は空になります。

   デフォルトは偽です (fork 時に消去します)。

   パラメータ:
      * **enable** -- 有効にする場合は 1、無効にする場合は 0。

   戻り値:
      0 on success, -1 on failure.

   Added in version 3.13.
