rotoscope 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9e3e40d016f9db6e000338a2324aa7e841596075
+  data.tar.gz: b09d90253edea8dadcef671c33e11fb482e6e505
+SHA512:
+  metadata.gz: 5ff87cb9a2d13fc25ad797d14e4f38d92132de716ee164d201032c953f96ca47d1e268413cc5c5041b50e6cdf0f7e1477a41ead4ccea7e40da5190675bc99761
+  data.tar.gz: 6021e1a40637d82234fc87da1a66d93e2917fd5379da67692420c502b92f7fac1b81df3beffa24896c9492ce6cfdcd0d1c72d5223f3e6f4ddd9e174070df521f

data/.clang-format

@@ -0,0 +1,2 @@
+---
+BasedOnStyle: Google

data/.github/PULL_REQUEST_TEMPLATE

@@ -0,0 +1,3 @@
+Make sure these are checked before submitting your PR — thank you!
+
+- [ ] `bin/fmt` was successfully run

data/.gitignore

@@ -0,0 +1,7 @@
+tmp
+lib/rotoscope/rotoscope.bundle
+lib/rotoscope/rotoscope.so
+.vscode
+*.gem
+.rubocop-*
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,15 @@
+inherit_from:
+  - http://shopify.github.io/ruby-style-guide/rubocop.yml
+
+AllCops:
+  Exclude:
+    - 'tmp/**/*'
+  TargetRubyVersion: 2.2
+
+Metrics/LineLength:
+  Exclude:
+    - 'test/**/*'
+
+Style/GlobalVars:
+  Exclude:
+    - 'ext/rotoscope/extconf.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.3.3

data/Gemfile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright 2017 Shopify
+
+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,215 @@
+# Rotoscope
+
+Rotoscope performs introspection of method calls in Ruby programs.
+
+## Status   [![status](https://circleci.com/gh/Shopify/rotoscope/tree/master.svg?style=shield&circle-token=cddbd315df7a81ab944adf4dfc14a5800cd589fc)](https://circleci.com/gh/Shopify/rotoscope/tree/master)
+
+Alpha!
+
+## Example
+
+```ruby
+require 'rotoscope'
+
+class Dog
+  def bark
+    Noisemaker.speak('woof!')
+  end
+end
+
+class Noisemaker
+  def self.speak(str)
+    puts(str)
+  end
+end
+
+log_file = File.expand_path('dog_trace.log')
+puts "Writing to #{log_file}..."
+
+Rotoscope.trace(log_file) do
+  dog1 = Dog.new
+  dog1.bark
+end
+```
+
+The resulting method calls are saved in the specified `dest` in the order they were received.
+
+Sample output:
+
+```
+event,entity,method_name,method_level,filepath,lineno
+call,"Dog","new",class,"example/dog.rb",19
+call,"Dog","initialize",instance,"example/dog.rb",19
+return,"Dog","initialize",instance,"example/dog.rb",19
+return,"Dog","new",class,"example/dog.rb",19
+call,"Dog","bark",instance,"example/dog.rb",4
+call,"Noisemaker","speak",class,"example/dog.rb",10
+call,"Noisemaker","puts",class,"example/dog.rb",11
+call,"IO","puts",instance,"example/dog.rb",11
+call,"IO","write",instance,"example/dog.rb",11
+return,"IO","write",instance,"example/dog.rb",11
+call,"IO","write",instance,"example/dog.rb",11
+return,"IO","write",instance,"example/dog.rb",11
+return,"IO","puts",instance,"example/dog.rb",11
+return,"Noisemaker","puts",class,"example/dog.rb",11
+return,"Noisemaker","speak",class,"example/dog.rb",12
+return,"Dog","bark",instance,"example/dog.rb",6
+```
+
+If you're interested solely in the flattened caller/callee list, you can pass the `flatten` option to retrieve that instead. This step will also remove all duplicate lines, which can produce significantly smaller output on large codebases.
+
+```ruby
+# ... same code as above
+
+Rotoscope.trace(log_file, flatten: true) do
+  dog1 = Dog.new
+  dog1.bark
+end
+```
+
+Sample output:
+
+```
+entity,method_name,method_level,filepath,lineno,caller_entity,caller_method_name,caller_method_level
+Dog,new,class,example/flattened_dog.rb,19,<ROOT>,<UNKNOWN>,<UNKNOWN>
+Dog,initialize,instance,example/flattened_dog.rb,19,Dog,new,class
+Dog,bark,instance,example/flattened_dog.rb,20,<ROOT>,<UNKNOWN>,<UNKNOWN>
+Noisemaker,speak,class,example/flattened_dog.rb,5,Dog,bark,instance
+Noisemaker,puts,class,example/flattened_dog.rb,11,Noisemaker,speak,class
+IO,puts,instance,example/flattened_dog.rb,11,Noisemaker,puts,class
+IO,write,instance,example/flattened_dog.rb,11,IO,puts,instance
+```
+
+## API
+
+- [Public Class Methods](#public-class-methods)
+  - [`trace`](#rotoscopetracedest-blacklist--flatten-false)
+  - [`new`](#rotoscopenewdest-blacklist)
+- [Public Instance Methods](#public-instance-methods)
+  - [`trace`](#rotoscopetraceblock)
+  - [`start_trace`](#rotoscopestart_trace)
+  - [`stop_trace`](#rotoscopestop_trace)
+  - [`mark`](#rotoscopemarkstr--)
+  - [`close`](#rotoscopeclose)
+  - [`state`](#rotoscopestate)
+  - [`closed?`](#rotoscopeclosed)
+  - [`log_path`](#rotoscopelog_path)
+
+---
+
+### Public Class Methods
+
+#### `Rotoscope::trace(dest, blacklist: [], flatten: false)`
+
+Writes all calls and returns of methods to `dest`, except for those whose filepath contains any entry in `blacklist`. `dest` is either a filename or an `IO`. The `flatten` option reduces the output data to a deduplicated list of method invocations and their caller, instead of all `call` and `return` events. Methods invoked at the top of the trace will have a caller entity of `<ROOT>` and a caller method name of `<UNKNOWN>`.
+
+```ruby
+Rotoscope.trace(dest) { |rs| ... }
+# or...
+Rotoscope.trace(dest, blacklist: ["/.gem/"], flatten: true) { |rs| ... }
+```
+
+#### `Rotoscope::new(dest, blacklist: [], flatten: false)`
+
+Same interface as `Rotoscope::trace`, but returns a `Rotoscope` instance, allowing fine-grain control via `Rotoscope#start_trace` and `Rotoscope#stop_trace`.
+```ruby
+rs = Rotoscope.new(dest)
+# or...
+rs = Rotoscope.new(dest, blacklist: ["/.gem/"], flatten: true)
+```
+
+---
+
+### Public Instance Methods
+
+#### `Rotoscope#trace(&block)`
+
+Similar to `Rotoscope::trace`, but does not need to create a file handle on invocation.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.trace do |rotoscope|
+  # code to trace...
+end
+```
+
+#### `Rotoscope#start_trace`
+
+Begins writing method calls and returns to the `dest` specified in the initializer.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.start_trace
+# code to trace...
+rs.stop_trace
+```
+
+#### `Rotoscope#stop_trace`
+
+Stops writing method invocations to the `dest`. Subsequent calls to `Rotoscope#start_trace` may be invoked to resume tracing.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.start_trace
+# code to trace...
+rs.stop_trace
+```
+
+#### `Rotoscope#mark(str = "")`
+
+ Inserts a marker '--- ' to divide output. Useful for segmenting multiple blocks of code that are being profiled. If `str` is provided, the line will be prefixed by '--- ', followed by the string passed.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.start_trace
+# code to trace...
+rs.mark('Something goes wrong here') # produces `--- Something goes wrong here` in the output
+# more code ...
+rs.stop_trace
+```
+
+#### `Rotoscope#close`
+
+Flushes the buffer and closes the file handle. Once this is invoked, no more writes can be performed on the `Rotoscope` object. Sets `state` to `:closed`.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.trace { |rotoscope| ... }
+rs.close
+```
+
+#### `Rotoscope#state`
+
+Returns the current state of the Rotoscope object. Valid values are `:open`, `:tracing` and `:closed`.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.state # :open
+rs.trace do
+  rs.state # :tracing
+end
+rs.close
+rs.state # :closed
+```
+
+#### `Rotoscope#closed?`
+
+Shorthand to check if the `state` is set to `:closed`.
+
+```ruby
+rs = Rotoscope.new(dest)
+rs.closed? # false
+rs.close
+rs.closed? # true
+```
+
+
+#### `Rotoscope#log_path`
+
+Returns the output filepath set in the Rotoscope constructor.
+
+```ruby
+dest = '/foo/bar/rotoscope.csv'
+rs = Rotoscope.new(dest)
+rs.log_path # "/foo/bar/rotoscope.csv"
+```

data/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# ==========================================================
+# Packaging
+# ==========================================================
+GEMSPEC = Gem::Specification.load('rotoscope.gemspec')
+
+require 'rubygems/package_task'
+Gem::PackageTask.new(GEMSPEC) do |pkg|
+end
+
+# ==========================================================
+# Ruby Extension
+# ==========================================================
+
+require 'rake/extensiontask'
+Rake::ExtensionTask.new('rotoscope', GEMSPEC) do |ext|
+  ext.lib_dir = 'lib/rotoscope'
+end
+
+task build: :compile
+
+task install: [:build] do |_t|
+  sh "gem build rotoscope.gemspec && gem install rotoscope-*.gem"
+end
+
+# ==========================================================
+# Testing
+# ==========================================================
+
+require 'rake/testtask'
+Rake::TestTask.new 'test' do |t|
+  t.test_files = FileList['test/*_test.rb']
+end
+task test: :build
+
+task default: :test

data/bin/fmt

@@ -0,0 +1,9 @@
+#! /usr/bin/env bash
+
+echo "Formatting C code..."
+find "$PWD" -iname lib/rotoscope/*.h -o -iname *.c | xargs clang-format -i -style=file
+
+echo "Formatting Ruby code..."
+bundle exec rubocop -a
+
+echo "Formatting complete."

data/dev.yml

@@ -0,0 +1,12 @@
+---
+name: rotoscope
+up:
+  - ruby: 2.3.3
+  - homebrew:
+    - clang-format
+  - bundler
+
+commands:
+  build: bundle exec rake build
+  test: bundle exec rake test
+  fmt: bin/fmt

data/ext/rotoscope/callsite.c

@@ -0,0 +1,78 @@
+#include "callsite.h"
+#include <ruby.h>
+#include <ruby/debug.h>
+
+VALUE empty_ruby_string;
+
+// Need the cfp field from this internal ruby structure.
+struct rb_trace_arg_struct {
+  // unused fields needed to make sure the cfp is at the
+  // correct offset
+  rb_event_flag_t unused1;
+  void *unused2;
+  void *cfp;
+  // rest of fields are unused
+};
+
+size_t ruby_control_frame_size;
+
+// We depend on MRI to store ruby control frames as an array
+// to determine the control frame size, which is used here to
+// get the caller's control frame
+static void *caller_cfp(void *cfp) {
+  return ((char *)cfp) + ruby_control_frame_size;
+}
+
+static VALUE dummy(VALUE self, VALUE first) {
+  if (first == Qtrue) {
+    rb_funcall(self, rb_intern("dummy"), 1, Qfalse);
+  }
+  return Qnil;
+}
+
+static void trace_control_frame_size(VALUE tpval, void *data) {
+  void **cfps = data;
+  rb_trace_arg_t *trace_arg = rb_tracearg_from_tracepoint(tpval);
+
+  if (cfps[0] == NULL) {
+    cfps[0] = trace_arg->cfp;
+  } else if (cfps[1] == NULL) {
+    cfps[1] = trace_arg->cfp;
+  }
+}
+
+rs_callsite_t c_callsite(rb_trace_arg_t *trace_arg) {
+  VALUE path = rb_tracearg_path(trace_arg);
+  return (rs_callsite_t){
+      .filepath = NIL_P(path) ? empty_ruby_string : path,
+      .lineno = FIX2INT(rb_tracearg_lineno(trace_arg)),
+  };
+}
+
+rs_callsite_t ruby_callsite(rb_trace_arg_t *trace_arg) {
+  void *old_cfp = trace_arg->cfp;
+
+  // Ruby uses trace_arg->cfp to get the path and line number
+  trace_arg->cfp = caller_cfp(trace_arg->cfp);
+  rs_callsite_t callsite = c_callsite(trace_arg);
+  trace_arg->cfp = old_cfp;
+
+  return callsite;
+}
+
+void init_callsite() {
+  empty_ruby_string = rb_str_new_literal("");
+  RB_OBJ_FREEZE(empty_ruby_string);
+  rb_global_variable(&empty_ruby_string);
+
+  VALUE tmp_obj = rb_funcall(rb_cObject, rb_intern("new"), 0);
+  rb_define_singleton_method(tmp_obj, "dummy", dummy, 1);
+
+  char *cfps[2] = {NULL, NULL};
+  VALUE tracepoint = rb_tracepoint_new(Qnil, RUBY_EVENT_C_CALL,
+                                       trace_control_frame_size, &cfps);
+  rb_tracepoint_enable(tracepoint);
+  rb_funcall(tmp_obj, rb_intern("dummy"), 1, Qtrue);
+  rb_tracepoint_disable(tracepoint);
+  ruby_control_frame_size = (size_t)cfps[0] - (size_t)cfps[1];
+}

data/ext/rotoscope/callsite.h

@@ -0,0 +1,17 @@
+#ifndef _INC_CALLSITE_H_
+#define _INC_CALLSITE_H_
+
+#include <ruby.h>
+#include <ruby/debug.h>
+
+typedef struct {
+  VALUE filepath;
+  unsigned int lineno;
+} rs_callsite_t;
+
+void init_callsite();
+
+rs_callsite_t c_callsite(rb_trace_arg_t *trace_arg);
+rs_callsite_t ruby_callsite(rb_trace_arg_t *trace_arg);
+
+#endif