summaryrefslogtreecommitdiff
path: root/lib/tracer.rb
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-17 20:16:23 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-17 20:16:23 +0000
commit747772bd430840b9133c1045a12e9564dedc76d3 (patch)
tree9c0c8d125cd8db824144e283116e3bc94ef462e9 /lib/tracer.rb
parent6e1b5723648423f55b46f7cf0a89476e5c61ac7c (diff)
* lib/tracer.rb: Improve documentation. Patch by Richard Ramsden.
[Ruby 1.9 - Feature #4720] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31618 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/tracer.rb')
-rw-r--r--lib/tracer.rb132
1 files changed, 115 insertions, 17 deletions
diff --git a/lib/tracer.rb b/lib/tracer.rb
index d1e088b..494de08 100644
--- a/lib/tracer.rb
+++ b/lib/tracer.rb
@@ -1,12 +1,63 @@
-# tracer.rb -
-# $Release Version: 0.3$
-# $Revision: 1.12 $
-# by Keiju ISHITSUKA(keiju@ishitsuka.com)
+##
+# = Tracer
#
-# --
+# Tracer outputs a source level execution trace of a Ruby program. It does
+# this by registering an event handler with <code>Kernel#set_trace_func</code>
+# for processing incoming events. It also provides methods for filtering
+# unwanted trace output (see Tracer.add_filter, Tracer.on, and Tracer.off).
#
+# == Example
#
+# Consider the following ruby script
#
+# class A
+# def square(a)
+# return a*a
+# end
+# end
+#
+# a = A.new
+# a.square(5)
+#
+# Running the above script using <code>ruby -r tracer example.rb</code> will
+# output the following trace to STDOUT (Note you can also explicitly
+# <code>require 'tracer'</code>)
+#
+# #0:<internal:lib/rubygems/custom_require>:38:Kernel:<: -
+# #0:example.rb:3::-: class A
+# #0:example.rb:3::C: class A
+# #0:example.rb:4::-: def square(a)
+# #0:example.rb:7::E: end
+# #0:example.rb:9::-: a = A.new
+# #0:example.rb:10::-: a.square(5)
+# #0:example.rb:4:A:>: def square(a)
+# #0:example.rb:5:A:-: return a*a
+# #0:example.rb:6:A:<: end
+# | | | | |
+# | | | | ---------------------+ event
+# | | | ------------------------+ class
+# | | --------------------------+ line
+# | ------------------------------------+ filename
+# ---------------------------------------+ thread
+#
+# Symbol table used for displaying incoming events:
+#
+# <tt>}</tt>:: call a C-language routine
+# <tt>{</tt>:: return from a C-language routine
+# <tt>></tt>:: call a Ruby method
+# <tt>C</tt>:: start a class or module definition
+# <tt>E</tt>:: finish a class or module definition
+# <tt>-</tt>:: execute code on a new line
+# <tt>^</tt>:: raise an exception
+# <tt><</tt>:: return from a Ruby method
+#
+# == Copyright
+#
+# by Keiju ISHITSUKA(keiju@ishitsuka.com)
+#
+#--
+# $Release Version: 0.3$
+# $Revision: 1.12 $
require "thread"
#
@@ -14,24 +65,29 @@ require "thread"
#
class Tracer
class << self
+ # display additional debug information (defaults to false)
attr_accessor :verbose
alias verbose? verbose
+ # output stream used to output trace (defaults to STDOUT)
attr_accessor :stdout
+
+ # mutex lock used by tracer for displaying trace output
attr_reader :stdout_mutex
- # display process id?
+ # display process id in trace output (defaults to false)
attr_accessor :display_process_id
alias display_process_id? display_process_id
- # display thread id?
+ # display thread id in trace output (defaults to true)
attr_accessor :display_thread_id
alias display_thread_id? display_thread_id
- # display builtin method call?
+ # display C-routine calls in trace output (defaults to false)
attr_accessor :display_c_call
alias display_c_call? display_c_call
end
+
Tracer::stdout = STDOUT
Tracer::verbose = false
Tracer::display_process_id = false
@@ -40,6 +96,7 @@ class Tracer
@stdout_mutex = Mutex.new
+ # Symbol table used for displaying trace information
EVENT_SYMBOL = {
"line" => "-",
"call" => ">",
@@ -52,7 +109,7 @@ class Tracer
"unknown" => "?"
}
- def initialize
+ def initialize # :nodoc:
@threads = Hash.new
if defined? Thread.main
@threads[Thread.main.object_id] = 0
@@ -65,11 +122,11 @@ class Tracer
@filters = []
end
- def stdout
+ def stdout # :nodoc:
Tracer.stdout
end
- def on
+ def on # :nodoc:
if block_given?
on
begin
@@ -83,20 +140,20 @@ class Tracer
end
end
- def off
+ def off # :nodoc:
set_trace_func nil
stdout.print "Trace off\n" if Tracer.verbose?
end
- def add_filter(p = proc)
+ def add_filter(p = proc) # :nodoc:
@filters.push p
end
- def set_get_line_procs(file, p = proc)
+ def set_get_line_procs(file, p = proc) # :nodoc:
@get_line_procs[file] = p
end
- def get_line(file, line)
+ def get_line(file, line) # :nodoc:
if p = @get_line_procs[file]
return p.call(line)
end
@@ -121,7 +178,7 @@ class Tracer
end
end
- def get_thread_no
+ def get_thread_no # :nodoc:
if no = @threads[Thread.current.object_id]
no
else
@@ -129,7 +186,7 @@ class Tracer
end
end
- def trace_func(event, file, line, id, binding, klass, *)
+ def trace_func(event, file, line, id, binding, klass, *) # :nodoc:
return if file == __FILE__
for p in @filters
@@ -159,7 +216,24 @@ class Tracer
end
+ # Reference to singleton instance of Tracer
Single = new
+
+ ##
+ # Start tracing
+ #
+ # === Example
+ #
+ # Tracer.on
+ # # code to trace here
+ # Tracer.off
+ #
+ # You can also pass a block:
+ #
+ # Tracer.on {
+ # # trace everything in this block
+ # }
+
def Tracer.on
if block_given?
Single.on{yield}
@@ -168,19 +242,42 @@ class Tracer
end
end
+ ##
+ # Disable tracing
+
def Tracer.off
Single.off
end
+ ##
+ # Register an event handler <code>p</code> which is called everytime a line
+ # in +file_name+ is executed.
+ #
+ # Example:
+ #
+ # Tracer.set_get_line_procs("example.rb", lambda { |line|
+ # puts "line number executed is #{line}"
+ # })
+
def Tracer.set_get_line_procs(file_name, p = proc)
Single.set_get_line_procs(file_name, p)
end
+ ##
+ # Used to filter unwanted trace output
+ #
+ # Example which only outputs lines of code executed within the Kernel class:
+ #
+ # Tracer.add_filter do |event, file, line, id, binding, klass, *rest|
+ # "Kernel" == klass.to_s
+ # end
+
def Tracer.add_filter(p = proc)
Single.add_filter(p)
end
end
+# :stopdoc:
SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__
if $0 == __FILE__
@@ -193,3 +290,4 @@ if $0 == __FILE__
elsif caller.count {|bt| /\A<internal:[^<>]+>:/ !~ bt} <= 1
Tracer.on
end
+# :startdoc: