set_trace_func(proc)    → proc
set_trace_func(nil)     → nil

Establishes proc as the handler for tracing, or disables tracing if the parameter is nil. proc takes up to six parameters: an event name, a filename, a line number, an object id, a binding, and the name of a class. proc is invoked whenever an event occurs. Events are: c-call (call a C-language routine), c-return (return from a C-language routine), call (call a Ruby method), class (start a class or module definition), end (finish a class or module definition), line (execute code on a new line), raise (raise an exception), and return (return from a Ruby method). Tracing is disabled within the context of proc.

  class Test
  def test
    a = 1
    b = 2
  end
  end

  set_trace_func proc { |event, file, line, id, binding, classname|
     printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname
  }
  t = Test.new
  t.test

    line prog.rb:11               false
  c-call prog.rb:11        new    Class
  c-call prog.rb:11 initialize   Object
c-return prog.rb:11 initialize   Object
c-return prog.rb:11        new    Class
    line prog.rb:12               false
    call prog.rb:2        test     Test
    line prog.rb:3        test     Test
    line prog.rb:4        test     Test
  return prog.rb:4        test     Test

Source Code

/*
*  call-seq:
*     set_trace_func(proc)    => proc
*     set_trace_func(nil)     => nil
*  
*  Establishes _proc_ as the handler for tracing, or disables
*  tracing if the parameter is +nil+. _proc_ takes up
*  to six parameters: an event name, a filename, a line number, an
*  object id, a binding, and the name of a class. _proc_ is
*  invoked whenever an event occurs. Events are: <code>c-call</code>
*  (call a C-language routine), <code>c-return</code> (return from a
*  C-language routine), <code>call</code> (call a Ruby method),
*  <code>class</code> (start a class or module definition),
*  <code>end</code> (finish a class or module definition),
*  <code>line</code> (execute code on a new line), <code>raise</code>
*  (raise an exception), and <code>return</code> (return from a Ruby
*  method). Tracing is disabled within the context of _proc_.
*
*      class Test
*      def test
*        a = 1
*        b = 2
*      end
*      end
*
*      set_trace_func proc { |event, file, line, id, binding, classname|
*         printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname
*      }
*      t = Test.new
*      t.test
*
*        line prog.rb:11               false
*      c-call prog.rb:11        new    Class
*      c-call prog.rb:11 initialize   Object
*    c-return prog.rb:11 initialize   Object
*    c-return prog.rb:11        new    Class
*        line prog.rb:12               false
*        call prog.rb:2        test     Test
*        line prog.rb:3        test     Test
*        line prog.rb:4        test     Test
*      return prog.rb:4        test     Test
*/


static VALUE
set_trace_func(obj, trace)
   VALUE obj, trace;
{
   rb_event_hook_t *hook;

   rb_secure(4);
   if (NIL_P(trace)) {
       trace_func = 0;
       rb_remove_event_hook(call_trace_func);
       return Qnil;
   }
   if (!rb_obj_is_proc(trace)) {
       rb_raise(rb_eTypeError, "trace_func needs to be Proc");
   }
   trace_func = trace;
   for (hook = event_hooks; hook; hook = hook->next) {
       if (hook->func == call_trace_func)
           return trace;
   }
   rb_add_event_hook(call_trace_func, RUBY_EVENT_ALL);
   return trace;
}