trip

trip is a concurrent tracer for the ruby programming language. It yields control between two threads, most likely the main thread and a thread that trip creates. It is implemented in pure ruby(no C) and with the help of "Thread#set_trace_func". It can be useful when building developer tools like a debugger or if you want to step through code progmatically at runtime.

Examples

1.

The code being traced is paused on method call and method return events by default.

def add(x,y)
  x + y
end

trip = Trip.new { add(20,50) }
e1 = trip.start  # Trip::Event  (for the method call of "#add")
e2 = trip.resume # Trip::Event  (for the method return of "#add")
e3 = trip.resume # returns nil  (thread exits)

2.

A predicate Proc can be implemented as a custom value. It receives an instance of Trip::Event that can support the Proc when it is making a decision on whether or not it should pause the tracer by returning false, or to continue by returning true.

class Planet
  def initialize(name)
    @name = name
  end

  def echo
    'ping'
  end
end

trip = Trip.new { Planet.new('earth').echo }
trip.pause? { |e| # pause on a method call
  e.name == 'call'
}
e1 = trip.start   # Trip::Event (for the method call of `Planet#initialize`)
e2 = trip.resume  # Trip::Event (for the method call of `Planet#echo`)
e3 = trip.resume  # returns nil (thread exits)

3.

Trip::Event#binding can be used to evaluate ruby while the trip thread is sleeping. The example returns the value of the local variable "x" after the add method has been called.

def add(x,y)
  x + y
end

trip = Trip.new { add(2,3) }
e1 = trip.start           # Trip::Event (for the method call of add)
x  = e1.binding.eval('x') # returns 2   (x is equal to 2)
trip.stop                 # thread exits

puts "x is equal to #{x}"

Install

rubygems:

gem install trip

git:

git clone https://github.com/rpag/trip.git
cd trip
gem build trip.gemspec
gem install *.gem

Contributing

1. Fork it ( https://github.com/rpag/trip/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

MIT, see LICENSE.txt for details.