Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo
lib
test
try
var
work
.gemspec
.gitignore
.index
.ruby
.travis.yml
.yardopts
Assembly
COPYING.rdoc
DEMO.rdoc
Gemfile
HISTORY.rdoc
MANIFEST
README.rdoc

README.rdoc

TracePoint

Home | Code | Mail

IMPORTANT!

The TracePoint gem is now deprecated. As of version 2.0.0, Ruby now has a built-in TracePoint API. Yes, it even uses the same name and has most of the same features. The API is a little different but it is very easy to adjust old code to the new API.

If this library lives on at all, it will be with a revamped API as part of the backports gem so that old versions of RubyGems can make use of new Ruby 2.0 feature.

Description

TracePoint is a Binding with the addition of event information. In theory it would function very well as the join-point for AOP. In practice it provides a better approach to #set_trace_func.

IMPOTRANT! TracePoint does not fully work under Ruby 1.9.0-1.9.3, not because there is anything wrong with TracePoint, but because Ruby 1.9 has a bug in `#set_trace_func` in which the binding parameter is incorrect.

*Rubinus Users*, Rubinus does not support #set_trace_func as this time so TracePoint can not help you.

Features

  • More versatile than #set_trace_func.

  • Easy to set multiple traces.

  • Can activate and deactivate traces on the fly.

Synopsis

Using TracePoint is simply a matter of setting the #trace procedure. For example to watch everything that happens during a Ruby process:

TracePoint.trace do |tp|
  puts "#{tp.self.class}\t#{tp.callee}\t#{tp.event}\t#{tp.return?}"
end

TracePoint.activate

1 + 1

Produces:

Object       line       false
Fixnum   +   c-call     false
Fixnum   +   c-return   false

Tracing can be deactivated and reactivated on the fly by calling #deactivate and #activate.

To add additional trace procedures, simply call the #trace method again. Trace procedures can also be named by providing a name argument to the #trace method. This allows traces to be added and removed without affecting other traces.

TracePoint.trace(:class_trace) do |tp|
  puts tp.self.class
end

TracePoint.trace(:method_trace) do |tp|
  puts tp.callee
end

# ...

TracePoint.clear(:class_trace)

Calling #clear with no arguments will remove all trace procedures and deactivate tracing.

Please see the API documentation for more information.

Install

Follow the usual procedure for installing via RubyGems:

$ gem install tracepoint

Copyrights

(BSD-2-Clause License)

Copyright © 2005,2010 Rubyworks, Thomas Sawyer

TracePoint is distributable in accordance with the terms of the FreeBSD license.

See COPYING.rdoc for details.