trip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2d170e305895c49de5afa27d65e21481a42b0647
+  data.tar.gz: d2245ff1028cbe489f101e53ac352c460db424d2
+SHA512:
+  metadata.gz: 28639d5f905547c812c2696d6451984f2624b7327180e597b15f9891f972693204a179914fd6731caf346a97549a9f9088c0d76f79e4fad11e3722377406fe0c
+  data.tar.gz: c4ae55b130f2bf502a7c3626178065ab97128e44da94a9d16685b410451af9501938236a0500dc1dc3e352d1173e1b2ef0acf07255671c0bbdaed8cfa4a45acf

data/.bundle/config

@@ -0,0 +1,3 @@
+---
+BUNDLE_PATH: ".gems"
+BUNDLE_DISABLE_SHARED_GEMS: '1'

data/.gitignore

@@ -0,0 +1,6 @@
+.gems/
+*.md~
+*.rb~
+*.rb#
+pkg/
+Gemfile.lock

data/.travis.yml

@@ -0,0 +1,10 @@
+install: bundle install
+script: ruby -S rake
+
+rvm:
+  - 1.9.3
+  - 2.1.3
+  - ruby-head
+
+notifications:
+  email: true

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+gemspec
+group :test do
+  gem 'minitest', require: ['minitest', 'minitest/spec']
+end
+

data/MIT-LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 rpag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+__trip__
+
+[![Build Status](https://travis-ci.org/rpag/trip.svg?branch=master)](https://travis-ci.org/rpag/trip)  
+[![Code Climate](https://codeclimate.com/github/rpag/trip/badges/gpa.svg)](https://codeclimate.com/github/rpag/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.
+
+
+__Limitations__
+
+trip is implemented with "Thread#set_trace_func". It can be a bottleneck, 
+especially when there are a large number of events being created. I have seen
+ruby grind to a halt when the codepath being traced is busy. It wouldn't be a good
+library to use with something like a production rails application, but it can be 
+useful when building developer tools.
+
+"Thread#set_trace_func" isn't well supported on any ruby implementation but the
+official MRI/CRuby implementations, so jruby+rubinius aren't supported.
+
+__Examples__
+
+__1.__
+
+The code being traced is paused on method call and method return events
+by default.
+
+```ruby
+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.
+
+```ruby
+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.
+
+```ruby
+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
+
+__License__
+
+See MIT-LICENSE.txt file.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:spec) do |t|
+  t.test_files = FileList['spec/*_spec.rb']
+  t.verbose = false
+end
+task :default => :spec

data/examples/concurrent.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH.unshift 'lib'
+require 'trip'
+
+#
+# an example method.
+# it assigns a local variable and returns control to the caller.
+#
+def example
+  x = 1
+end
+
+#
+# initialize Trip with a block that calls the example() method.
+# the trace doesn't start yet.
+#
+trip = Trip.new do 
+  example()
+end
+
+#
+# the tracer can be paused on certain events.
+#
+trip.pause? do |event| 
+  event.name == 'call' or event.name == 'return' 
+end
+
+#
+# start trip.
+# e1 and e2 reference Trip::Event objects. e3 ends up referencing nil.
+# nil is returned when trip has finished.
+#
+e1 = trip.start  # before assignment of 'x'
+e2 = trip.resume # after assignment of 'x'
+e3 = trip.resume # finished
+
+#
+# print the value of 'x'.
+# the local variable 'x' belongs to the binding closed over by e2(method return).
+#
+print 'x is equal to "%s".' % e2.binding.eval('x')
+

data/examples/time.rb

@@ -0,0 +1,15 @@
+$LOAD_PATH.unshift 'lib'
+require 'trip'
+
+class Phone
+  def self.call
+    sleep(2)
+    'ring ring'
+  end
+end
+
+trip = Trip.new { Phone.call }
+trip.pause? { |e| e.name == 'call' or e.name == 'return' }
+t1 = trip.start.created_at
+t2 = trip.resume.created_at
+puts "it took around #{t2 - t1} seconds"

data/lib/trip.rb

@@ -0,0 +1,167 @@
+class Trip
+  require 'thread'
+  require_relative 'trip/event'
+  require_relative 'trip/version'
+
+  NotStartedError  = Class.new(RuntimeError)
+  NotFinishedError = Class.new(RuntimeError)
+
+  RUN_STATE   = 'run'
+  SLEEP_STATE = 'sleep'
+  END_STATE   = [nil, false]
+  CALL_E      = ['call', 'c-call']
+  RETURN_E    = ['return', 'c-return']
+  PAUSE_P     = Proc.new { |event|
+    CALL_E.include?(event.name) or RETURN_E.include?(event.name)
+  }
+
+  #
+  #  @param [Proc] &block
+  #    a block of code
+  #
+  #  @return [Trip]
+  #    returns an instance of Trip
+  #
+  def initialize(&block)
+    if block.equal?(nil)
+      raise ArgumentError, 'expected to receive a block but none given'
+    end
+    @thread = nil
+    @block  = block
+    @queue  = nil
+    @pause  = PAUSE_P
+  end
+
+  #
+  # @raise [ArgumentError]
+  #   when no arguments are received
+  #
+  # @param [Proc] callable
+  #   accepts a Proc or a block
+  #
+  # @return [Proc] 
+  #   returns a Proc
+  #
+  def pause?(callable = nil, &block)
+    pause = callable || block
+    if pause.equal?(nil)
+      raise ArgumentError, 'expected to receive a block but none given'
+    end
+    @pause = pause
+  end
+
+  #
+  #  @return [Boolean]
+  #    returns true when a trace has started
+  #
+  def started?
+    @thread != nil
+  end
+
+  #
+  #  @return [Boolean]
+  #    returns true when a tracer thread is running
+  #
+  def running?
+    @thread and @thread.status == RUN_STATE
+  end
+
+  #
+  #  @return [Boolean]
+  #    returns true when a tracer thread has finished
+  #
+  def finished?
+    @thread and END_STATE.include?(@thread.status)
+  end
+
+  #
+  #  @return [Boolean]
+  #    returns true when a tracer thread is sleeping
+  #
+  def sleeping?
+    @thread and @thread.status == SLEEP_STATE
+  end
+
+  #
+  #  resume the tracer
+  #
+  #  @raise [Trip::NotStartedError]
+  #    when the start method has not been called yet
+  #
+  #  @return [Trip::Event, nil]
+  #    returns an event or nil
+  #
+  def resume
+    unless started?
+      raise NotStartedError, 'the tracer has not been started'
+    end
+    if sleeping?
+      @thread.wakeup
+      @queue.deq
+    end
+  end
+
+  #
+  # start the tracer
+  #
+  # @raise [Trip::NotFinishedError]
+  #   when a trace is already in progress
+  #   
+  # @return [Trip::Event, nil]
+  #   returns an event, or nil 
+  #
+  def start
+    if started? and !finished?
+      raise NotFinishedError, 'a trace is still in progress'
+    end
+    @queue = Queue.new
+    @thread = Thread.new do
+      Thread.current.set_trace_func method(:on_event).to_proc
+      @block.call
+      Thread.current.set_trace_func(nil)
+      @queue.enq(nil)
+    end
+    @queue.deq
+  end
+
+  #
+  # stop the tracer
+  #
+  # @return [nil]
+  #   returns nil
+  #
+  def stop
+    if @thread
+      @thread.set_trace_func(nil)
+      @thread.exit
+      @thread.join
+      nil
+    end
+  end
+
+private
+  def on_event(name, file, lineno, method, binding, classname)
+    event = Event.new name, {
+      file:      file, 
+      lineno:    lineno, 
+      module:    classname,
+      method:    method,
+      binding:   binding
+    }
+    if event.file != __FILE__ and @pause.call(event)
+      @queue.enq(event)
+      Thread.stop
+    end
+  rescue Exception => e
+    warn <<-CRASH.each_line.map(&:lstrip)
+    (trip) the tracer has crashed! :(
+
+    #{e.class}:
+    #{e.message}
+
+    BACKTRACE
+    #{e.backtrace.join("\n")}
+    CRASH
+    Thread.current.set_trace_func(nil)
+  end
+end

data/lib/trip/event.rb

@@ -0,0 +1,31 @@
+class Trip::Event < BasicObject
+  Kernel  = ::Kernel
+  Time    = ::Time
+  CALLS   = %w(call c-call)
+  RETURNS = %w(return c-return)
+
+  attr_reader :name, :created_at
+
+  def initialize(name, event)
+    @name       = name
+    @event      = event
+    @created_at = Time.now
+  end
+
+  [:file, :lineno, :module, :method, :binding].each do |name|
+    define_method(name) { @event[name] }
+  end
+
+  #
+  # @return [Binding]
+  #   returns a binding for an instance of {Trip::Event}
+  #
+  def __binding__
+    Kernel.binding
+  end
+
+  def inspect
+    inspect_m = Kernel.instance_method(:inspect).bind(self)
+    inspect_m.call
+  end
+end

data/lib/trip/version.rb

@@ -0,0 +1,3 @@
+class Trip
+  VERSION = '0.1.0'
+end

data/spec/setup.rb

@@ -0,0 +1,3 @@
+require 'bundler/setup'
+Bundler.require :default, :test
+Minitest.autorun

data/spec/trip_spec.rb

@@ -0,0 +1,157 @@
+require_relative 'setup'
+describe Trip do
+  class Planet
+    def echo(message)
+      return message
+    end
+  end
+
+  before do
+    @planet = Planet.new
+    @trip   = Trip.new { @planet.echo('ping') }
+  end
+
+  after do
+    unless @trip.finished?
+      @trip.stop
+    end
+  end
+
+  describe '#initialize' do
+    it 'raises an ArgumentError without a block' do
+      assert_raises(ArgumentError) { Trip.new }
+    end
+  end
+
+  describe '#start' do
+    it 'returns an instance of Trip::Event' do
+      assert Trip::Event === @trip.start
+    end
+
+    it 'returns nil with a false pause predicate' do
+      @trip.pause? { false }
+      assert_equal nil, @trip.start
+    end
+
+    it 'raises Trip::NotFinishedError' do
+      @trip.start
+      assert_raises(Trip::NotFinishedError) { @trip.start }
+    end
+  end
+
+  describe '#sleeping?' do
+    it 'returns true' do
+      @trip.start
+      assert_equal true, @trip.sleeping?
+    end
+
+    it 'returns false' do
+      @trip.start
+      @trip.resume while @trip.resume
+      assert_equal false, @trip.sleeping?
+    end
+  end
+
+  describe '#started?' do
+    it 'returns true' do
+      @trip.start
+      assert_equal true, @trip.started?
+    end
+
+    it 'returns false' do
+      assert_equal false, @trip.started?
+    end
+  end
+  
+  describe '#resume' do
+    it 'raises Trip::NotStartedError' do
+      assert_raises(Trip::NotStartedError) { @trip.resume }
+    end
+  end
+
+  describe '#pause?' do
+    it 'raises an ArgumentError' do
+      assert_raises(ArgumentError) { @trip.pause? }
+    end
+    
+    it 'accepts a Proc' do
+      obj = Proc.new {}
+      assert_equal obj, @trip.pause?(obj)
+    end
+  end
+
+  describe '#finished?' do
+    it 'returns true' do
+      @trip.start
+      @trip.resume while @trip.resume
+      assert_equal true, @trip.finished?
+    end
+
+    it 'returns false' do
+      @trip.start
+      assert_equal false, @trip.finished? 
+    end
+
+    it 'returns nil' do
+      assert_equal nil, @trip.finished?
+    end
+  end
+
+  describe '#running?' do
+    it 'returns false' do
+      @trip.start
+      @trip.resume while @trip.resume
+      assert_equal false, @trip.running?
+    end
+
+    it 'returns nil' do
+      assert_equal nil, @trip.running?
+    end
+  end
+
+  describe Trip::Event do
+    describe '#module' do
+      it 'returns a Module' do
+        e1 = @trip.start
+        assert_equal Planet, e1.module
+      end
+    end
+
+    describe '#method' do
+      it 'returns a method name' do
+        e1 = @trip.start
+        assert_equal :echo, e1.method
+      end
+    end
+
+    describe '#file' do
+      it 'returns a path' do
+        e1 = @trip.start
+        assert_equal __FILE__, e1.file
+      end
+    end
+
+    describe '#lineno' do
+      it 'returns an Integer' do
+        e1 = @trip.start
+        assert_kind_of Integer, e1.lineno
+      end
+    end
+
+    describe '#binding' do
+      it 'returns a Binding with access to the local variable "message"' do 
+        @trip.pause? { |e| e.name == 'call' or e.name == 'return' }
+        e1 = @trip.start
+        e2 = @trip.resume
+        assert_equal 'ping', e2.binding.eval('message')
+      end
+    end
+
+    describe '#__binding__' do
+      it 'returns a Binding for an instance of Trip::Event' do
+        e1 = @trip.start
+        assert Trip::Event === e1.__binding__.eval('self')
+      end
+    end
+  end
+end

data/trip.gemspec

@@ -0,0 +1,11 @@
+$LOAD_PATH << 'lib'
+require 'trip'
+Gem::Specification.new do |g|
+  g.name        = 'trip'
+  g.author	= 'rpag'
+  g.email	= 'rpag@singletonclass.com'
+  g.version     = Trip::VERSION
+  g.summary     = 'concurrent ruby tracer'
+  g.description = 'concurrent ruby tracer built with Thread#set_trace_func'
+  g.files	= `git ls-files`.split($/)
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: trip
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rpag
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-03 00:00:00.000000000 Z
+dependencies: []
+description: concurrent ruby tracer built with Thread#set_trace_func
+email: rpag@singletonclass.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".bundle/config"
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- MIT-LICENSE.txt
+- README.md
+- Rakefile
+- examples/concurrent.rb
+- examples/time.rb
+- lib/trip.rb
+- lib/trip/event.rb
+- lib/trip/version.rb
+- spec/setup.rb
+- spec/trip_spec.rb
+- trip.gemspec
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: concurrent ruby tracer
+test_files: []
+has_rdoc: