26.5. "hotshot" --- ハイパフォーマンス・ロギング・プロファイラ
**************************************************************

バージョン 2.2 で追加.

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

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

バージョン 2.5 で変更: 以前より意味のある結果が得られているはずです。
かつては時間計測の中核部分に致命的なバグがありました.

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

class hotshot.Profile(logfile[, lineevents[, linetimings]])

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


26.5.1. Profile オブジェクト
============================

Profile オブジェクトには以下のメソッドがあります:

Profile.addinfo(key, value)

   プロファイル出力の際、任意のラベル名を追加します。

Profile.close()

   ログファイルを閉じ、プロファイラを終了します。

Profile.fileno()

   プロファイラのログファイルのファイル・デスクリプタを返します。

Profile.run(cmd)

   スクリプト環境で "exec" 互換文字列のプロファイルをおこないます。
   "__main__" モジュールのグローバル変数は、スクリプトのグローバル変数
   、ローカル変数の両方に使われます。

Profile.runcall(func, *args, **keywords)

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

Profile.runctx(cmd, globals, locals)

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

Profile.start()

   プロファイラを開始します。

Profile.stop()

   プロファイラを停止します。


26.5.2. hotshot データの利用
============================

バージョン 2.2 で追加.

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

hotshot.stats.load(filename)

   *filename* から hotshot データを読み込み、 "pstats.Stats" クラスの
   インスタンスを返します。

参考:

  "profile" モジュール
     "profile" モジュールの "Stats" クラス


26.5.3. 使用例
==============

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

   >>> 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)
    .
    .
    .
