gctrack 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92838d06f2819fc114876a76cb748508d1d1468d
-  data.tar.gz: 403295552c868ce6284861af1071cb14350f6bd8
+  metadata.gz: 4388d6afd81b4cfb83867cb06a566660b460142d
+  data.tar.gz: b8f4b6ed72cee918d87ad60161b08eeae4875645
 SHA512:
-  metadata.gz: 5942ef39807b64f69e448325265f9bb2b6a7575de22534073c11d58f19525bc6641beb10b0996a66d758c62e60becfcfa191bddd0a6527c706b640aee3b7ff5e
-  data.tar.gz: 9f9e5f8c6bb6b976b15d9e09f85e34492245bc7d040b0a6bbe1b167d3854d53d15af4a472d7e4a97631e27a59516980657535b0a7ba3ed7b838f853ed806e7a7
+  metadata.gz: 6e52f68e61eab3e758420725acf7f23b124b4c7230e03529291e2710bc53a509ddd5006636c63f885c41971e8a6a6b4911b60a9f59480ad6b339bed0e54fdd61
+  data.tar.gz: c138d07a3ac9685280b1bde07397e82d31ba5402a434c0c5ee543841dbe5d8ebbff5a882989c60145a06520cf82a2b0bc944aa007500111c4b41ae33ba0d964a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gctrack (0.0.1)
+    gctrack (0.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,2 +1,55 @@
+[![Gem Version](https://badge.fury.io/rb/gctrack.svg)](https://badge.fury.io/rb/gctrack)
+[![Build Status](https://travis-ci.org/Shopify/gctrack.svg?branch=master)](https://travis-ci.org/Shopify/gctrack)
+
 ## GCTrack
 
+The GCTrack extension lets you monitor incremental Garbage Collector (GC) information, the GC introduced in Ruby v2.2.
+
+### Getting started
+
+#### #1 Add the dependency
+
+GCTrack is published to [rubygems.org](https://rubygems.org/gems/gctrack). 
+Simply add it as a dependency to your `Gemfile`
+
+```ruby
+gem 'gctrack', '~> 0.1.0'
+```
+
+#### #2 Enable the extension
+
+```ruby
+require 'gctrack'
+
+GC::Tracker.enable # returns true, if the Tracker is now enabled
+```
+
+#### #3 Record data
+
+```ruby
+GC::Tracker.start_record # returns true, if a new record was started
+# DO ACTUAL WORK
+gc_cycles, gc_duration_ns = GC::Tracker.end_record
+```
+
+`#end_record` will return the `gc_cycles` (the amount of gc cycles observed) and `gc_duration_ns` (their cumulative duration in 
+nanoseconds), since the last invocation of `#start_record`. You can also invoke `#start_record` recursively as so:
+
+```ruby
+GC::Tracker.start_record # Start a first record 
+do_work_on(one)
+GC::Tracker.start_record # Start a second record 
+do_work_on(two)
+inner_data = GC::Tracker.end_record # Collect results from second record
+do_work_on(three)
+outter_data = GC::Tracker.end_record # Collect results from first record
+```
+
+In this example, the Array `inner_data` will only contain the GC information resulted of executing `do_work_on(two)`, while 
+`outter_data` will contain the GC information resulted from the three exectutions: `do_work_on` `one`, `two` and `three`. 
+
+Effectively, records are stacked and data from a GC cycle will be added to all "currently" records.
+
+## License
+
+[The MIT License (MIT)](LICENSE.md)

data/ext/gctrack/gctrack.c

@@ -49,13 +49,15 @@ gctracker_enabled()
 static void 
 gctracker_hook(VALUE tpval, void *data)
 {
-  if (!gctracker_enabled()) {
+  if (!gctracker_enabled() && !last_record) {
     return;
   }
   rb_trace_arg_t *tparg = rb_tracearg_from_tracepoint(tpval);
   switch (rb_tracearg_event_flag(tparg)) {
     case RUBY_INTERNAL_EVENT_GC_ENTER: {
-      last_enter = nanotime();
+      if (gctracker_enabled()) {
+        last_enter = nanotime();
+      }
     }
       break;
     case RUBY_INTERNAL_EVENT_GC_EXIT: {
@@ -68,18 +70,40 @@ gctracker_hook(VALUE tpval, void *data)
   }
 }
 
-static void
+static bool
 create_tracepoint() 
 {
   rb_event_flag_t events;
   events = RUBY_INTERNAL_EVENT_GC_ENTER | RUBY_INTERNAL_EVENT_GC_EXIT;
   tracepoint = rb_tracepoint_new(0, events, gctracker_hook, (void *) NULL);
   if (NIL_P(tracepoint)) {
-    rb_raise(rb_eRuntimeError, "GCTracker: Couldn't create tracepoint!");
+    return false;
   }
   rb_global_variable(&tracepoint);
+  return true;
 }
 
+/*
+ * call-seq:
+ *    GC::Tracker.start_record  -> true or false
+ *
+ * Starts recording GC cycles and their duration. Returns +true+ if the 
+ * recording was started, +false+ otherwise. If the record could be started
+ * an GC::Tracker#end_record invocation will always return data for the record, 
+ * otherwise that invocation would return +nil+.
+ * One case where +false+ would be returned is if the Tracker isn't enabled.
+ * #start_record can be nested. These records will have a parent-child relationship,
+ * where the parent will contain all GC data of the child.
+ *
+ *    GC::Tracker.enabled?      # true
+ *    GC::Tracker.start_record  # true
+ *    GC::Tracker.start_record  # true
+ *    GC::Tracker.end_record    # [2, 12654] from the second #start_record
+ *    GC::Tracker.disable       # true
+ *    GC::Tracker.start_record  # false
+ *    GC::Tracker.end_record    # [3, 15782] from the first #start_record, contains the data from the first record
+ *    GC::Tracker.end_record    # nil from the last #start_record, that returned false
+ */
 static VALUE
 gctracker_start_record(int argc, VALUE *argv, VALUE klass)
 {
@@ -97,6 +121,26 @@ gctracker_start_record(int argc, VALUE *argv, VALUE klass)
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ *    GC::Tracker.end_record  -> Array or nil
+ *
+ * Ends the recording of the last started record and return the 
+ * the collected information. 
+ * The array contains two numbers: The amount of GC cycles observed and 
+ * the cumulative duration in nanoseconds of these cycles. If multiple recordings
+ * were started they will be be popped from the stack of records and their 
+ * values will be returned. 
+ * GC data gathered is in all records of the stack. 
+ *
+ *    GC::Tracker.start_record  # true
+ *    GC::Tracker.start_record  # true
+ *    GC::Tracker.end_record    # [2, 12654] amount of cycles and duration since the second #start_record
+ *    GC::Tracker.end_record    # [3, 15782] GC data since the first #start_record, including the data above
+ *    GC::Tracker.disable       # true
+ *    GC::Tracker.start_record  # false
+ *    GC::Tracker.end_record    # nil
+ */
 static VALUE
 gctracker_end_record(int argc, VALUE *argv, VALUE klass)
 {
@@ -115,43 +159,79 @@ gctracker_end_record(int argc, VALUE *argv, VALUE klass)
   return stats;
 }
 
+/*
+ * call-seq:
+ *    GC::Tracker.enabled?  -> true or false
+ *
+ * Returns +true+ if the Tracker is enabled, +false+ otherwise.
+ *
+ *    GC::Tracker.enabled?  # false
+ *    GC::Tracker.enable    # true
+ *    GC::Tracker.enabled?  # true
+ *    GC::Tracker.enable    # true
+ */
+static VALUE 
+gctracker_enabled_p(int argc, VALUE *argv, VALUE klass)
+{
+  return gctracker_enabled() ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *    GC::Tracker.enable   -> true or false
+ *
+ * Globally enables the tracker. Returns +true+ if the Tracker is 
+ * enabled after this call (whether it enabled it or not), +false+ otherwise.
+ *
+ *    GC::Tracker.disable   # true
+ *    GC::Tracker.enabled?  # false
+ *    GC::Tracker.enable    # true
+ *    GC::Tracker.enabled?  # true
+ */
 static VALUE
 gctracker_enable(int argc, VALUE *argv, VALUE klass)
 {
-  if (NIL_P(tracepoint)) {
-    create_tracepoint();
-  }
-
   if (gctracker_enabled()) {
     return Qtrue;
   }
 
+  if (NIL_P(tracepoint)) {
+    if(!create_tracepoint()) {
+      return Qfalse;
+    }
+  }
+
   rb_tracepoint_enable(tracepoint);
   if (!gctracker_enabled()) {
-    rb_raise(rb_eRuntimeError, "GCTracker: Couldn't enable tracepoint!");
+    return Qfalse;
   }
 
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ *    GC::Tracker.disable   -> true or false
+ *
+ * Globally disables the tracker. Returns +true+ if the Tracker is 
+ * disabled after this call (whether it disabled it or not), +false+ otherwise.
+ *
+ *    GC::Tracker.enabled?  # true
+ *    GC::Tracker.disable   # true
+ *    GC::Tracker.enabled?  # false
+ *    GC::Tracker.disable   # true
+ */
 static VALUE
 gctracker_disable(VALUE self)
 {
   if (!gctracker_enabled()) {
-    return Qfalse;
+    return Qtrue;
   }
 
   rb_tracepoint_disable(tracepoint);
   if (gctracker_enabled()) {
-    rb_raise(rb_eRuntimeError, "GCTracker: Couldn't disable tracepoint!");
+    return Qfalse;
   } 
-
-  while (last_record) {
-    record_t *record = last_record;
-    last_record = record->parent;
-    free(record);
-  }
-  last_record = NULL;
   
   return Qtrue;
 }
@@ -163,6 +243,7 @@ Init_gctrack()
   VALUE cTracker = rb_define_module_under(mGC, "Tracker");
 
   rb_define_module_function(cTracker, "enable", gctracker_enable, 0);
+  rb_define_module_function(cTracker, "enabled?", gctracker_enabled_p, 0);
   rb_define_module_function(cTracker, "disable", gctracker_disable, 0);
 
   rb_define_module_function(cTracker, "start_record", gctracker_start_record, 0);

data/gctrack.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'gctrack'
-  s.version = '0.0.1'
+  s.version = '0.1.0'
   s.summary = 'Track Ruby GC events'
   s.description = <<-DOC
     This gem can be used to track Ruby GC tracepoints that are normally only visible through GC extensions.

data/lib/gctrack.rb

@@ -0,0 +1 @@
+require 'gctrack/gctrack'

data/test/test_gctrack.rb

@@ -1,5 +1,5 @@
 require 'test/unit'
-require 'gctrack/gctrack'
+require 'gctrack'
 
 class TestGctrack < Test::Unit::TestCase
   def test_enable
@@ -9,15 +9,11 @@ class TestGctrack < Test::Unit::TestCase
   end
 
   def test_disable
-    assert !GC::Tracker.disable
+    assert GC::Tracker.disable
     assert GC::Tracker.enable
     assert GC::Tracker.disable
   end
 
-  def test_returns_false_when_not_enabled
-    assert_equal false, GC::Tracker.disable
-  end
-
   def test_enabled_generates_events
     assert GC::Tracker.enable
     assert GC::Tracker.start_record
@@ -51,10 +47,20 @@ class TestGctrack < Test::Unit::TestCase
     assert GC::Tracker.end_record.nil?
   end
 
-  def test_no_data_for_started_records_on_disable
+  def test_enabled_returns_accrodingly
+    assert !GC::Tracker.enabled?
+    GC::Tracker.enable
+    assert GC::Tracker.enabled?
+  ensure
+    GC::Tracker.disable
+  end
+
+  def test_data_for_started_records_on_disable
     assert GC::Tracker.enable
     assert GC::Tracker.start_record
     assert GC::Tracker.disable
+    assert !GC::Tracker.start_record
+    assert !GC::Tracker.end_record.nil?
     assert GC::Tracker.end_record.nil?
   ensure
     GC::Tracker.disable

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gctrack
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Scott Francis
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-07 00:00:00.000000000 Z
+date: 2017-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -59,6 +59,7 @@ files:
 - ext/gctrack/extconf.rb
 - ext/gctrack/gctrack.c
 - gctrack.gemspec
+- lib/gctrack.rb
 - test/test_gctrack.rb
 homepage: https://github.com/Shopify/gctrack
 licenses: