pask 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0efd58f652add7f0a2601ca79c2bd14cd1a332c2
+  data.tar.gz: f2a1dd7ec682b6723e74c93089b379ec9bfaab84
+SHA512:
+  metadata.gz: f05dcb5e9c2dbe6c913a0f6a7454560ce1ba45e9a278efdecdfccf5b8697371426755d786cf354a8cd42b2f9df9a3e03e6b5bc11b96c49c4740cfb7196f16f15
+  data.tar.gz: 3d5b48e49f330ca4899ae8daf6af9b764f3fac1e34a1e9a18f624e2d51340542155b95207ff35639c822f7e0de4064bef5b7b97682bd89f49aa83473fb2afa2b

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.pryrc

@@ -0,0 +1,3 @@
+require "bundler"
+Bundler.require :default
+Pry.plugins.values.map(&:disable!)

data/.ruby-version

@@ -0,0 +1 @@
+2

data/.travis.yml

@@ -0,0 +1,9 @@
+rvm:
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head
+
+notifications:
+  email: true

data/ChangeLog.txt

@@ -0,0 +1,3 @@
+== v0.1.0
+  - release!
+  it works. quiet release.

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+gemspec
+gem "binding.repl"
+
+group :development do
+  gem "rake"
+end
+
+group :development, :test do
+  gem "pry"
+  gem "pry-doc"
+  gem "minitest", require: "minitest/autorun"
+end

data/README.md

@@ -0,0 +1,74 @@
+__OVERVIEW__
+
+| Project         | pask
+|:----------------|:--------------------------------------------------
+| Homepage        | https://github.com/robgleeson/pask
+| Build           | [![Build Status](https://travis-ci.org/robgleeson/pask.png?branch=master)](https://travis-ci.org/robgleeson/pask)
+
+__DESCRIPTION__
+
+pask is a concurrent tracer written with the power of `Thread#set_trace_func`.
+
+__EXAMPLES__
+
+```ruby
+tracer = Pask.new
+tracer.trace { Person.call }
+event1 = tracer.start # the event for "Person.call called"
+event2 = tracer.resume # the event for "Person.call returned"
+event3 = tracer.resume # returns nil (no more code to trace)
+```
+
+__REPL IN YO TRACER__
+
+pask produces instance's of `Pask::Event` when it traces code. an event is returned to
+the caller and opens up some exciting possibilities(due to the wonders of `Binding`):
+
+```ruby
+def call
+  x = 1
+  p x
+end
+
+tracer = Pask.new
+tracer.trace { Person.call }
+event1 = tracer.start
+event.binding.pry # start pry inside 'call', before assignment of x.
+```
+
+__RUBIES__
+
+- MRI
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.0+
+
+__CONTRIBUTE!__
+
+[fork it](https://github.com/robgleeson/binding.repl/fork), clone it, change! <br>
+open a pull request :)
+
+some tips for working on the project:
+```
+cd $CLONED_DIR
+bundle install
+rake test # run tests
+```
+
+__INSTALL__
+
+    $ gem install pask
+
+__SEE ALSO__
+
+- [machine.repl](https://github.com/robgleeson/machine.repl)<br>
+  the webmachine-ruby repl/debugger.
+
+- [examples/ directory](https://github.com/robgleeson/pask/tree/master/examples)<br>
+  examples in the `examples/` directory. `$ rake examples` runs em all.
+
+__LICENSE__
+
+see UNLICENSE.txt. public domain.

data/Rakefile

@@ -0,0 +1,24 @@
+require "bundler/gem_tasks"
+
+desc "run the tests"
+task :test do
+  Dir["test/*_test.rb"].each do |file|
+    require_relative(file)
+  end
+end
+task :default => :test
+
+desc "run the examples in examples/*.rb"
+task :examples do
+  Dir["examples/*.rb"].each do |example|
+    sh "ruby %s" % [example]
+    puts
+  end
+end
+
+desc "repeat test runs twenty times to look for race conditions"
+task :race do
+  20.times do |index|
+    Rake::Task["test"].execute
+  end
+end

data/UNLICENSE.txt

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

data/examples/concurrent_binding_trace.rb

@@ -0,0 +1,15 @@
+require "bundler/setup"
+Bundler.require :default
+
+def call
+  2+2
+  x = 2
+end
+
+tracer = Pask.new
+tracer.interested? { |e| e.call? or e.return? }
+tracer.trace { call }
+event1 = tracer.start
+puts "[-] call() called. value of x is #{event1.binding.eval('x').inspect}."
+event2 = tracer.resume
+puts "[-] call() returned. value of x is now #{event2.binding.eval('x')}."

data/examples/count_method_calls_trace.rb

@@ -0,0 +1,11 @@
+require "bundler"
+Bundler.require :default
+def call
+end
+
+puts "[-] counting 11 method calls. 10 ruby method calls, one C method call."
+tracer = Pask.new
+tracer.interested? { |e| e.call? or e.c_call? }
+tracer.trace { 10.times { call } }
+events = tracer.consume!
+puts "[-] code traced. count done! a total of: #{events.size}"

data/examples/time_trace.rb

@@ -0,0 +1,13 @@
+require "bundler"
+Bundler.require :default
+
+def call
+  sleep(1)
+end
+
+puts "[-] going to sleep for a second, hold tight!"
+tracer = Pask.new
+tracer.interested? { |e| e.call? or e.return? }
+tracer.trace { call }
+events = tracer.consume!
+puts "[-] #{events.at(0).signature} took #{events.at(1) - events.at(0)} second(s) to finish"

data/lib/pask.rb

@@ -0,0 +1,114 @@
+class Pask
+  require "thread"
+  require_relative "pask/event"
+
+  NotStartedError  = Class.new(RuntimeError)
+  NotFinishedError = Class.new(RuntimeError)
+
+  VERSION          = "0.1.0".freeze
+  RUN_STATE        = "run".freeze
+  SLEEP_STATE      = "sleep".freeze
+  TERMINATED_STATE = [nil, false].freeze
+  CATCH_ALL        = Proc.new { true }
+
+  def self.version
+    VERSION
+  end
+
+  def initialize
+    @thread = nil
+    @queue = nil
+    @predicate = CATCH_ALL
+    @predicate_copy = nil
+    @block = nil
+    @block_copy = nil
+  end
+
+  def interested?(callable = nil, &block)
+    predicate = callable || block
+    unless predicate
+      raise ArgumentError, "no predicate given to #{__method__}()"
+    end
+    @predicate = predicate
+  end
+
+  def started?
+    if @queue and @thread
+      true
+    else
+      false
+    end
+  end
+
+  def running?
+    if @thread and @thread.status == RUN_STATE
+      true
+    else
+      false
+    end
+  end
+
+  def finished?
+    if @thread and TERMINATED_STATE.include?(@thread.status)
+      true
+    else
+      false
+    end
+  end
+
+  def sleeping?
+    if @thread and @thread.status == SLEEP_STATE
+      true
+    else
+      false
+    end
+  end
+
+  def resume
+    unless started?
+      raise NotStartedError, "tracer has not been started"
+    end
+    if sleeping?
+      @thread.wakeup
+      @queue.deq
+    end
+  end
+
+  def start
+    if started? and not finished?
+      raise NotFinishedError, "tracer has not finished"
+    end
+    @queue = Queue.new
+    @thread = Thread.new do
+      @predicate_copy, @block_copy = @predicate, @block
+      Thread.current.set_trace_func method(:on_event).to_proc
+      @block_copy.call
+      Thread.current.set_trace_func(nil)
+      @queue.enq nil
+    end
+    @queue.deq
+  end
+
+  def trace(&block)
+    @block = block
+  end
+
+  def consume!
+    events = [start]
+    current_event = nil
+    events.push(current_event) while current_event = resume
+    events
+  end
+
+private
+  def on_event(name, file, lineno, method, binding, _)
+    event = Event.new name, file: file, method: method, lineno: lineno, binding: binding
+    if event.file != __FILE__ and @predicate_copy.call(event)
+      @queue.enq(event)
+      Thread.stop
+    end
+  rescue Exception => e
+    warn "TRACER CRASHED"
+    Thread.current.set_trace_func(nil)
+  end
+end

data/lib/pask/event.rb

@@ -0,0 +1,96 @@
+class Pask::Event
+  CALL        = "call"
+  C_CALL      = "c-call"
+  RETURN      = "return"
+  C_RETURN    = "c-return"
+  KNOWN_NAMES = [CALL, C_CALL, RETURN, C_RETURN].map!(&:freeze)
+
+  def initialize(name, other)
+    @name = name
+    @other = other
+    @created_at = Time.now
+    @signature = nil
+    @to_f = nil
+    @emit_by = binding.eval "self"
+  end
+
+  def emit_by
+    # FIXME: messed up for C calls and returns. maybe return nil for them?
+    @emit_by
+  end
+
+  def to_f
+    @to_f ||= @created_at.to_f
+  end
+
+  def created_at
+    @created_at
+  end
+
+  def file
+    @other[:file]
+  end
+
+  def lineno
+    @other[:lineno]
+  end
+
+  def emit_by_method
+    @other[:method]
+  end
+
+  def binding
+    @other[:binding]
+  end
+
+  def __binding__
+    Kernel.binding
+  end
+
+  def any_call?
+    call? or c_call?
+  end
+
+  def return?
+    @name == RETURN
+  end
+
+  def c_return?
+    @name == C_RETURN
+  end
+
+  def call?
+    @name == CALL
+  end
+
+  def c_call?
+    @name == C_CALL
+  end
+
+  def any_return?
+    return? or c_return?
+  end
+
+  def origin?(mod)
+    if emit_by.respond_to?(:ancestors)
+      emit_by.ancestors.include?(mod)
+    else
+      mod === emit_by
+    end
+  end
+
+  def signature
+    @signature ||= if emit_by.kind_of?(Module)
+      [emit_by, @method].join(".")
+    else
+      [emit_by.class, @method].join("#")
+    end
+  end
+
+  def -(other)
+    unless other.respond_to?(:to_f)
+      raise TypeError, "cannot coerce argument to a float"
+    end
+    to_f - other.to_f
+  end
+end

data/pask.gemspec

@@ -0,0 +1,15 @@
+require File.expand_path('../lib/pask', __FILE__)
+Gem::Specification.new do |gem|
+  gem.name          = "pask"
+  gem.authors       = ["Public Domain"]
+  gem.email         = ["robert@flowof.info"]
+  gem.description   = "concurrent tracer implemented on top of Thread#set_trace_func"
+  gem.summary       = gem.description
+  gem.homepage      = "https://github.com/robgleeson/pask"
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ["lib"]
+  gem.license	    = "Public Domain"
+  gem.version       = Pask.version
+end

data/test/pask_event_test.rb

@@ -0,0 +1,12 @@
+require_relative "setup"
+class TracerEventTest < MiniTest::Test
+  def test_return_value_of_binding
+    event = Pask::Event.new "call", {binding: TOPLEVEL_BINDING}
+    assert_equal TOPLEVEL_BINDING, event.binding
+  end
+
+  def test_return_value_of___binding__
+    event = Pask::Event.new "call", {binding: TOPLEVEL_BINDING}
+    assert_equal event, event.__binding__.eval("self")
+  end
+end

data/test/pask_test.rb

@@ -0,0 +1,133 @@
+require_relative 'setup'
+class PaskTest < MiniTest::Test
+  def setup
+    @code = Code.new
+  end
+
+  class Code
+    def call
+      2+2
+      x = 5
+    end
+  end
+
+  def test_start
+    tracer = Pask.new
+    tracer.interested? { |e| e.return? }
+    tracer.trace { @code.call }
+    assert_instance_of Pask::Event, tracer.start
+  end
+
+  def test_start_without_a_match
+    tracer = Pask.new
+    tracer.interested? { false }
+    tracer.trace { @code.call }
+    assert_equal nil, tracer.start
+  end
+
+  def test_start_on_started_tracer
+    tracer = Pask.new
+    tracer.trace { @code.call }
+    tracer.start
+    assert_raises(Pask::NotFinishedError) { tracer.start }
+  end
+
+  def test_consume!
+    tracer = Pask.new
+    tracer.interested? { |e| e.call? or e.return? }
+    tracer.trace { @code.call }
+    events = tracer.consume!
+    assert_equal 2, events.size
+  end
+
+  def test_sleeping_predicate_on_started_tracer
+    tracer = Pask.new
+    tracer.interested? { |event| event.return? }
+    tracer.trace { @code.call }
+    tracer.start
+    assert_equal true, tracer.sleeping?
+  end
+
+  def test_sleeping_predicate_on_finished_tracer
+    tracer = Pask.new
+    tracer.interested? { |event| event.return? }
+    tracer.trace { @code.call }
+    tracer.start
+    tracer.resume while tracer.resume
+    assert_equal false, tracer.sleeping?
+  end
+
+  def test_started_predicate_on_started_tracer
+    tracer = Pask.new
+    tracer.interested? { |event| event.return? }
+    tracer.trace { @code.call }
+    tracer.start
+    assert_equal true, tracer.started?
+  end
+
+  def test_started_predicate_on_unstarted_tracer
+    tracer = Pask.new
+    assert_equal false, tracer.started?
+  end
+
+  def test_resume_on_unstarted_tracer
+    tracer = Pask.new
+    assert_raises(Pask::NotStartedError) { tracer.resume }
+  end
+
+  def test_interested_predicate_without_block
+    tracer = Pask.new
+    assert_raises(ArgumentError) { tracer.interested? }
+  end
+
+  def test_interested_predicate_with_callable
+    obj = Proc.new {}
+    tracer = Pask.new
+    assert_equal obj, tracer.interested?(obj)
+  end
+
+  def test_finished_predicate_on_finished_tracer
+    tracer = Pask.new
+    tracer.trace { @code.call }
+    tracer.start
+    tracer.resume while tracer.resume
+    assert_equal true, tracer.finished?
+  end
+
+  def test_finished_predicate_on_unstarted_tracer
+    tracer = Pask.new
+    assert_equal false, tracer.finished?
+  end
+
+  def test_finished_predicate_on_started_tracer
+    tracer = Pask.new
+    tracer.interested? { |event| event.return? }
+    tracer.trace { @code.call }
+    tracer.start
+    assert_equal false, tracer.finished?
+  end
+
+  def test_running_predicate_on_dead_tracer
+    tracer = Pask.new
+    tracer.interested? { |event| event.return? }
+    tracer.trace { @code.call }
+    tracer.start
+    tracer.resume
+    assert_equal false, tracer.running?
+  end
+
+  def test_running_predicate_on_unstarted_tracer
+    tracer = Pask.new
+    assert_equal false, tracer.running?
+  end
+
+  def test_concurrent_trace_with_binding_and_local_variable
+    tracer = Pask.new
+    tracer.interested? { |e| e.call? or e.return? }
+    tracer.trace { @code.call }
+    event = tracer.start
+    assert_equal nil, event.binding.eval("x")
+    event = tracer.resume
+    assert_equal 5, event.binding.eval("x")
+  end
+end

data/test/setup.rb

@@ -0,0 +1,2 @@
+require "bundler/setup"
+Bundler.require :default, :test

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: pask
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Public Domain
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-14 00:00:00.000000000 Z
+dependencies: []
+description: concurrent tracer implemented on top of Thread#set_trace_func
+email:
+- robert@flowof.info
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".pryrc"
+- ".ruby-version"
+- ".travis.yml"
+- ChangeLog.txt
+- Gemfile
+- README.md
+- Rakefile
+- UNLICENSE.txt
+- examples/concurrent_binding_trace.rb
+- examples/count_method_calls_trace.rb
+- examples/time_trace.rb
+- lib/pask.rb
+- lib/pask/event.rb
+- pask.gemspec
+- test/pask_event_test.rb
+- test/pask_test.rb
+- test/setup.rb
+homepage: https://github.com/robgleeson/pask
+licenses:
+- Public Domain
+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 tracer implemented on top of Thread#set_trace_func
+test_files:
+- test/pask_event_test.rb
+- test/pask_test.rb
+- test/setup.rb
+has_rdoc: