= TracePoint

{Home}[http://rubyworks.github.com/tracepoint] | {Code}[http://github.com/rubyworks/tracepoint] | {Mail}[http://google.groups.com/group/rubyworks-mailinglist]

{<img src="http://travis-ci.org/rubyworks/tracepoint.png" />}[http://travis-ci.org/rubyworks/tracepoint]

== 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)

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

See COPYING.rdoc for details.

Tracepoint

Install / Use

README

...