\section{\module{hotshot} ---
         ハイパフォーマンス・ロギング・プロファイラ}

\declaremodule{standard}{hotshot}
\modulesynopsis{コードの大半が C で書かれたハイパフォーマンス・ロギン
グ・プロファイラ}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Anthony Baxter}{anthony@interlink.com.au}

\versionadded{2.2}

このモジュールは \module{_hotshot} C モジュールへのより良いインターフェー
スを提供します。Hotshot は既存の \refmodule{profile} に置き換わるもの
です。その大半が C で書かれているため、\refmodule{profile} に比べパフォー
マンス上の影響がはるかに少なく済みます。

\begin{notice}[注意]
\module{hotshot} は C モジュールでプロファイル中のオーバーヘッドを
極力小さくすることに焦点を絞っており、その代わりに後処理時間の長さという
つけを払います。通常の使用法についてはこのモジュールではなく
\module{cProfile} を使うことを推奨します。\module{hotshot} は保守され
ておらず、将来的には標準ライブラリから外されるかもしれません。
\end{notice}

\versionchanged[以前より意味のある結果が得られているはずです。
かつては時間計測の中核部分に致命的なバグがありました]{2.5}

\begin{notice}[注意]
\module{hotshot}プロファイラはまだスレッド環境ではうまく動作しません。
測定したいコード上でプロファイラを実行するためにスレッドを使わない版の
スクリプトを使う方法が有用です。
\end{notice}

\begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{,
                           linetimings}}}

プロファイラ・オブジェクト。引数 \var{logfile} はプロファイル・データ
のログを保存するファイル名です。引数 \var{lineevents} はソースコー
ドの1 行ごとにイベントを発生させるか、関数の呼び出し/リターンのときだ
け発生させるかを指定します。デフォルトの値は \code{0} (関数の呼び出し/
リターンのときだけログを残す)です。引数 \var{linetimings} は時間情報を
記録するかどうかを指定します。デフォルトの値は \code{1} (時間情報を記
録する)です。

\end{classdesc}

\subsection{プロファイル・オブジェクト \label{hotshot-objects}}

プロファイル・オブジェクトは以下のメソッドを持っています。

\begin{methoddesc}[Profile]{addinfo}{key, value}
プロファイル出力の際、任意のラベル名を追加します。
\end{methoddesc}

\begin{methoddesc}[Profile]{close}{}
ログファイルを閉じ、プロファイラを終了します。
\end{methoddesc}

\begin{methoddesc}[Profile]{fileno}{}
プロファイラのログファイルのファイル・ディスクリプタを返します。
\end{methoddesc}

\begin{methoddesc}[Profile]{run}{cmd}
スクリプト環境で \keyword{exec} 互換文字列のプロファイルをおこないます。
\refmodule[main]{__main__} モジュールのグローバル変数は、スクリプトの
グローバル変数、ローカル変数の両方に使われます。
\end{methoddesc}

\begin{methoddesc}[Profile]{runcall}{func, *args, **keywords}
単一の呼び出し可能オブジェクトのプロファイルをおこないます。位置依存引
数やキーワード引数を追加して呼び出すオブジェクトに渡すこともできます。
呼び出しの結果はそのまま返されます。例外が発生したときはプロファイリン
グが無効になり、例外をそのまま伝えるようになっています。
\end{methoddesc}

\begin{methoddesc}[Profile]{runctx}{cmd, globals, locals}

指定した環境で \keyword{exec} 互換文字列の評価をおこないます。文字列の
コンパイルはプロファイルを開始する前におこなわれます。
\end{methoddesc}

\begin{methoddesc}[Profile]{start}{}
プロファイラを開始します。
\end{methoddesc}

\begin{methoddesc}[Profile]{stop}{}
プロファイラを停止します。
\end{methoddesc}


\subsection{hotshot データの利用}

\declaremodule{standard}{hotshot.stats}
\modulesynopsis{Hotshot の統計分析}

\versionadded{2.2}

このモジュールは hotshot プロファイル・データを標準の \module{pstats}
オブジェクトにロードします。

\begin{funcdesc}{load}{filename}
\var{filename} から hotshot データを読み込み、\class{pstats.Stats} ク
ラスのインスタンスを返します。
\end{funcdesc}

\begin{seealso}
  \seemodule{profile}{\module{profile} モジュールの \class{Stats} クラス}
\end{seealso}


\subsection{使用例 \label{hotshot-example}}

これは Python の``ベンチマーク'' pystone を使った例です。実行にはやや
時間がかかり、巨大な出力ファイルを生成するので注意してください。

\begin{verbatim}
>>> import hotshot, hotshot.stats, test.pystone
>>> prof = hotshot.Profile("stones.prof")
>>> benchtime, stones = prof.runcall(test.pystone.pystones)
>>> prof.close()
>>> stats = hotshot.stats.load("stones.prof")
>>> stats.strip_dirs()
>>> stats.sort_stats('time', 'calls')
>>> stats.print_stats(20)
         850004 function calls in 10.090 CPU seconds

   Ordered by: internal time, call count

   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
        1    3.295    3.295   10.090   10.090 pystone.py:79(Proc0)
   150000    1.315    0.000    1.315    0.000 pystone.py:203(Proc7)
    50000    1.313    0.000    1.463    0.000 pystone.py:229(Func2)
 .
 .
 .
\end{verbatim}
