Class: Tracer

Inherits:
Object
  • Object
show all
Defined in:
lib/tracer.rb

Overview

tracer main class

Constant Summary collapse

EVENT_SYMBOL =

Symbol table used for displaying trace information

{
  "line" => "-",
  "call" => ">",
  "return" => "<",
  "class" => "C",
  "end" => "E",
  "raise" => "^",
  "c-call" => "}",
  "c-return" => "{",
  "unknown" => "?"
}
Single =

Reference to singleton instance of Tracer

new

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Tracer

:nodoc:



112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/tracer.rb', line 112

def initialize # :nodoc:
  @threads = Hash.new
  if defined? Thread.main
    @threads[Thread.main.object_id] = 0
  else
    @threads[Thread.current.object_id] = 0
  end

  @get_line_procs = {}

  @filters = []
end

Class Attribute Details

.display_c_call ⇒ Object Also known as: display_c_call?

display C-routine calls in trace output (defaults to false)



87
88
89
 
# File 'lib/tracer.rb', line 87

def display_c_call
  @display_c_call
end

.display_process_id ⇒ Object Also known as: display_process_id?

display process id in trace output (defaults to false)



79
80
81
 
# File 'lib/tracer.rb', line 79

def display_process_id
  @display_process_id
end

.display_thread_id ⇒ Object Also known as: display_thread_id?

display thread id in trace output (defaults to true)



83
84
85
 
# File 'lib/tracer.rb', line 83

def display_thread_id
  @display_thread_id
end

.stdout ⇒ Object

output stream used to output trace (defaults to STDOUT)



73
74
75
 
# File 'lib/tracer.rb', line 73

def stdout
  @stdout
end

.stdout_mutex ⇒ Object (readonly)

mutex lock used by tracer for displaying trace output



76
77
78
 
# File 'lib/tracer.rb', line 76

def stdout_mutex
  @stdout_mutex
end

.verbose ⇒ Object Also known as: verbose?

display additional debug information (defaults to false)



69
70
71
 
# File 'lib/tracer.rb', line 69

def verbose
  @verbose
end

Class Method Details

.add_filter(p = proc) ⇒ Object

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



275
276
277
 
# File 'lib/tracer.rb', line 275

def Tracer.add_filter(p = proc)
  Single.add_filter(p)
end

.off ⇒ Object

Disable tracing



248
249
250
 
# File 'lib/tracer.rb', line 248

def Tracer.off
  Single.off
end

.on ⇒ Object

Start tracing

Example

Tracer.on
# code to trace here
Tracer.off

You can also pass a block:

Tracer.on {
  # trace everything in this block
}



237
238
239
240
241
242
243
 
# File 'lib/tracer.rb', line 237

def Tracer.on
  if block_given?
    Single.on{yield}
  else
    Single.on
  end
end

.set_get_line_procs(file_name, p = proc) ⇒ Object

Register an event handler p 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}"
})



262
263
264
 
# File 'lib/tracer.rb', line 262

def Tracer.set_get_line_procs(file_name, p = proc)
  Single.set_get_line_procs(file_name, p)
end

Instance Method Details

#add_filter(p = proc) ⇒ Object

:nodoc:



148
149
150
 
# File 'lib/tracer.rb', line 148

def add_filter(p = proc) # :nodoc:
  @filters.push p
end

#get_line(file, line) ⇒ Object

:nodoc:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/tracer.rb', line 156

def get_line(file, line) # :nodoc:
  if p = @get_line_procs[file]
    return p.call(line)
  end

  unless list = SCRIPT_LINES__[file]
    begin
      f = File::open(file)
      begin
        SCRIPT_LINES__[file] = list = f.readlines
      ensure
        f.close
      end
    rescue
      SCRIPT_LINES__[file] = list = []
    end
  end

  if l = list[line - 1]
    l
  else
    "-\n"
  end
end

#get_thread_no ⇒ Object

:nodoc:



181
182
183
184
185
186
187
 
# File 'lib/tracer.rb', line 181

def get_thread_no # :nodoc:
  if no = @threads[Thread.current.object_id]
    no
  else
    @threads[Thread.current.object_id] = @threads.size
  end
end

#off ⇒ Object

:nodoc:



143
144
145
146
 
# File 'lib/tracer.rb', line 143

def off # :nodoc:
  set_trace_func nil
  stdout.print "Trace off\n" if Tracer.verbose?
end

#on ⇒ Object

:nodoc:



129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/tracer.rb', line 129

def on # :nodoc:
  if block_given?
    on
    begin
      yield
    ensure
      off
    end
  else
    set_trace_func method(:trace_func).to_proc
    stdout.print "Trace on\n" if Tracer.verbose?
  end
end

#set_get_line_procs(file, p = proc) ⇒ Object

:nodoc:



152
153
154
 
# File 'lib/tracer.rb', line 152

def set_get_line_procs(file, p = proc) # :nodoc:
  @get_line_procs[file] = p
end

#stdout ⇒ Object

:nodoc:



125
126
127
 
# File 'lib/tracer.rb', line 125

def stdout # :nodoc:
  Tracer.stdout
end

#trace_func(event, file, line, id, binding, klass) ⇒ Object

:nodoc:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/tracer.rb', line 189

def trace_func(event, file, line, id, binding, klass, *) # :nodoc:
  return if file == __FILE__

  for p in @filters
    return unless p.call event, file, line, id, binding, klass
  end

  return unless Tracer::display_c_call? or
    event != "c-call" && event != "c-return"

  Tracer::stdout_mutex.synchronize do
    if EVENT_SYMBOL[event]
      stdout.printf("<%d>", $$) if Tracer::display_process_id?
      stdout.printf("#%d:", get_thread_no) if Tracer::display_thread_id?
      if line == 0
        source = "?\n"
      else
        source = get_line(file, line)
      end
      printf("%s:%d:%s:%s: %s",
             file,
             line,
             klass || '',
             EVENT_SYMBOL[event],
             source)
    end
  end

end