module function Kernel.#set_trace_func

Ruby インタプリタのイベントをトレースする Proc オブジェクトとして指定された proc を登録します。 nil を指定するとトレースがオフになります。

Ruby インタプリタがプログラムを実行する過程で、メソッドの呼び出しや式の評価などのイベントが発生する度に、以下で説明する6個の引数とともに登録された Proc オブジェクトを実行します。

標準添付の debug、tracer、 profile はこの組み込み関数を利用して実現されています。

ブロックパラメータの意味

渡す Proc オブジェクトのパラメータは

proc{|event, file, line, id, binding, klass| ... }

で、意味は以下の通りです。

event

実行のタイプを表す、以下のいずれかの文字列。

  "line":      式の評価。
  "call":      メソッドの呼び出し。
  "return":    メソッド呼び出しからのリターン。
  "c-call":    Cで記述されたメソッドの呼び出し。
  "c-return":  Cで記述されたメソッド呼び出しからのリターン。
  "class":     クラス定義、特異クラス定義、モジュール定義への突入。
  "end":       クラス定義、特異クラス定義、モジュール定義の終了。
  "raise":     例外の発生。

file

実行中のプログラムのソースファイル名 (文字列)。

line

実行中のプログラムのソースファイル上の行番号 (整数)。

id

event に応じ、以下のものが渡されます。第六ブロック引数の klass と対応しています。

    line
        最後に呼び出されたメソッドを表す Symbol オブジェクト。
        トップレベルでは nil。
    call/return/c-call/c-return
        呼び出された/リターンするメソッドを表す Symbol オブジェクト。
    class/end
        nil。
    raise
        最後に呼び出されたメソッドを表す Symbol オブジェクト。
        トップレベルでは nil。

binding

実行中のプログラムのコンテキストを表す Binding オブジェクト。

klass

event に応じ、以下のものが渡されます。第四ブロック引数の id と対応しています。

    line
        最後に呼び出されたメソッドが属するクラスを表す
        Class オブジェクト。トップレベルでは nil。
    call/return/c-call/c-return
        呼び出された/リターンするメソッドが属するクラス
        を表す Class オブジェクト。
    class/end
        nil。
    raise
        最後に呼び出されたメソッドが属するクラスを表す
        Class オブジェクト。トップレベルでは nil。

[PARAM] proc:

トレース用 Proc オブジェクトを指定します。nil を指定した場合、トレースをオフにします。

[RETURN]

proc を返します。

例:

set_trace_func lambda {|*arg|
  p arg
}
class Foo
end
43.to_s

# ----結果----
# ["c-return", "..", 1, :set_trace_func, #<Binding:0xf6ceb8>, Kernel]
# ["line", "..", 4, nil, #<Binding:0x10cbcd8>, nil]
# ["c-call", "..", 4, :inherited, #<Binding:0x10cba98>, Class]
# ["c-return", "..", 4, :inherited, #<Binding:0x10cb858>, Class]
# ["class", "..", 4, nil, #<Binding:0x10cb600>, nil]
# ["end", "..", 5, nil, #<Binding:0x10cb3f0>, nil]
# ["line", "..", 6, nil, #<Binding:0x10cb1e0>, nil]
# ["c-call", "..", 6, :to_s, #<Binding:0x10cafd0>, Fixnum]
# ["c-return", "..", 6, :to_s, #<Binding:0x10cad78>, Fixnum]

[SEE_ALSO] Kernel.#caller