ruby-static-tracing 0.0.13 → 0.0.14

data/lib/ruby-static-tracing/platform.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
 module StaticTracing
+  # Platform detection for ruby-static-tracing
   module Platform
-    extend self
+    module_function
 
+    # Returns true if platform is linux
     def linux?
       /linux/.match(RUBY_PLATFORM)
     end
 
+    # Returns true if platform is darwin
     def darwin?
       /darwin/.match(RUBY_PLATFORM)
     end
 
+    # Returns true if platform is known to be supported
     def supported_platform?
       linux? || darwin?
     end

data/lib/ruby-static-tracing/provider.rb

@@ -1,77 +1,101 @@
 # frozen_string_literal: true
 
 module StaticTracing
-  class Provider #:nodoc:
+  # A wrapper for a USDT tracepoint provider
+  # This corresponds to a namespace of tracepoints
+  # By convention, we will often create one per
+  # class or module.
+  class Provider
     attr_accessor :name
+
+    # Provider couldn't be found in collection
     class ProviderNotFound < StandardError; end
 
     class << self
+      # Gets a provider by name
+      # or creates one if not exists
       def register(namespace)
         providers[namespace] ||= new(namespace)
       end
 
+      # Gets a provider instance by name
       def fetch(namespace)
         providers.fetch(namespace) do
           raise ProviderNotFound
         end
       end
 
+      # Enables each provider, ensuring
+      # it is loaded into memeory
       def enable!
-        providers.values.each do |provider|
-          provider.enable
-        end
+        providers.values.each(&:enable)
       end
 
+      # Forcefully disables all providers,
+      # unloading them from memory
       def disable!
-        providers.values.each do |provider|
-          provider.disable
-        end
+        providers.values.each(&:disable)
       end
 
       def clean
+        # FIXME: this should free first
         @providers = {}
       end
 
       private
 
+      # A global collection of providers
       def providers
         @providers ||= {}
       end
     end
 
-    attr_reader :namespace
+    attr_reader :namespace, :tracepoints
 
-    def initialize(namespace)
-      if StaticTracing::Platform.supported_platform?
-        provider_initialize(namespace)
-      else
-        StaticTracing.issue_disabled_tracepoints_warning
+    # Adds a new tracepoint to this provider
+    # FIXME - should this be a dictionary, or are duplicate names allowed?
+    def add_tracepoint(tracepoint, *args)
+      if tracepoint.is_a?(String)
+        tracepoint = Tracepoint.new(namespace, tracepoint, *args)
+      elsif tracepoint.is_a?(Tracepoint)
+        @tracepoints << tracepoint
       end
-      @namespace = namespace
-    end
-
-    def add_tracepoint(method_name, *args)
-      Tracepoint.new(namespace, method_name, *args)
+      tracepoint
     end
 
-# FIXME - how to store list of tracepoints on provider? Allocate map in C?
-#    def tracepoints
-#      []
-#    end
+    # Enable the provider, loading it into memory
     def enable
+      @enabled = _enable_provider
     end
 
+    # Disables the provider, unloading it from memory
     def disable
+      @enabled = !_disable_provider
     end
 
-    # FIXME add binding to check if enabled
+    # Returns true if the provider is enabled,
+    # meaning it is loaded into memory
     def enabled?
+      @enabled
     end
 
-    def destroy
-    end
+    # Only supported on systems (linux) where backed by file
+    def path; end
+
+    def destroy; end
+
+    private
 
-    def provider_initialize(*)
+    # ALWAYS use register, never call .new dilectly
+    def initialize(namespace)
+      if StaticTracing::Platform.supported_platform?
+        provider_initialize(namespace)
+        @enabled = false
+      else
+        StaticTracing.issue_disabled_tracepoints_warning
+      end
+      @namespace = namespace
+      @tracepoints = []
     end
   end
 end

data/lib/ruby-static-tracing/tracepoint.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module StaticTracing
-  class Tracepoint #:nodoc:
-
+  class Tracepoint
     class InvalidArgumentError < StandardError
       def initialize(argument, expected_type)
         error_message = <<~ERROR_MESSAGE
@@ -16,23 +15,29 @@ module StaticTracing
     end
     class InvalidArgType < StandardError; end
 
-    VALID_ARGS_TYPES = [Integer, String]
+    VALID_ARGS_TYPES = [Integer, String].freeze
 
-    attr_reader :provider, :name, :args
+    attr_reader :provider_name, :name, :args
 
-    def initialize(provider, name, *args)
-      @provider = provider
+    # Creates a new tracepoint.
+    # If a provider by the name specified doesn't exist already,
+    # one will be added implicitly.
+    def initialize(provider_name, name, *args)
+      @provider_name = provider_name
       @name = name
       validate_args(args)
       @args = args
 
       if StaticTracing::Platform.supported_platform?
-        tracepoint_initialize(provider, name, args)
+        tracepoint_initialize(provider_name, name, args)
+        provider.add_tracepoint(self)
       else
         StaticTracing.issue_disabled_tracepoints_warning
       end
     end
 
+    # Fire a tracepoint, sending the data off to be received by
+    # a tracing program like dtrace
     def fire(*values)
       values.each_with_index do |arg, i|
         raise InvalidArgumentError.new(arg, args[i]) unless arg.is_a?(args[i])
@@ -40,13 +45,18 @@ module StaticTracing
       _fire_tracepoint(values)
     end
 
-    def enabled?
+    def provider
+      Provider.fetch(@provider_name)
     end
 
+    # Returns true if a tracepoint is currently
+    # attached to, indicating we should fire it
+    def enabled?; end
+
     private
 
     def validate_args(values)
-      raise InvalidArgType unless values.all? { |value|  VALID_ARGS_TYPES.include?(value) }
+      raise InvalidArgType unless values.all? { |value| VALID_ARGS_TYPES.include?(value) }
     end
   end
 end

data/lib/ruby-static-tracing/tracepoints.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module StaticTracing
+  # FIXME: - why do we need this class? We should store tracepoints
+  # on providers, and get the list of all tracepoints from the list of providers
   class Tracepoints
     class ProviderMissingError < StandardError; end
     class TracepointMissingError < StandardError; end

data/lib/ruby-static-tracing/tracer/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'unmixer'
 using Unmixer
 

data/lib/ruby-static-tracing/tracer/concerns/latency_tracer.rb

@@ -3,6 +3,8 @@
 module StaticTracing
   module Tracer
     module Concerns
+      # Including this module will cause the target
+      # to have latency tracers added around every method
       module Latency
         def self.included(base)
           methods = base.public_instance_methods(false)

data/lib/ruby-static-tracing/tracer/helpers.rb

@@ -1,17 +1,17 @@
+# frozen_string_literal: true
+
 module StaticTracing
   module Tracer
     module Helpers
-      extend self
+      module_function
 
       def underscore(class_name)
-        class_name.gsub(/::/, '_').
-          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-          gsub(/([a-z\d])([A-Z])/,'\1_\2').
-          tr("-", "_").
-          downcase
+        class_name.gsub(/::/, '_')
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                  .tr('-', '_')
+                  .downcase
       end
     end
   end
 end
-
-

data/lib/ruby-static-tracing/tracer/latency.rb

@@ -3,7 +3,7 @@
 module StaticTracing
   module Tracer
     class Latency < Base
-      set_wrapping_function -> (*args, &block) {
+      set_wrapping_function lambda { |*args, &block|
         start_time = StaticTracing.nsec
         result = super(*args, &block)
         duration = StaticTracing.nsec - start_time

data/lib/ruby-static-tracing/tracer/stack.rb

@@ -2,9 +2,11 @@
 
 module StaticTracing
   module Tracer
+    # A stack tracer gets the stack trace at point when
+    # the tracer is executed
     class Stack < Base
-      set_wrapping_function -> (*args, &block) {
-        current_stack = self.send(:caller).join("\n")
+      set_wrapping_function lambda { |*args, &block|
+        current_stack = send(:caller).join("\n")
         method_name = __method__.to_s
         provider = Tracer::Helpers.underscore(self.class.name)
         Tracepoints.get(provider, method_name).fire(method_name, current_stack)

data/lib/ruby-static-tracing/tracers.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module StaticTracing
+  # Tracers are a layer of abstraction above tracepoints. They are opinionated
+  # and contextual ways of applying tracepoints to an application.
   class Tracers
+    # Error for an invalid tracer
     class InvalidTracerError < StandardError
       def initialize
         msg = <<~MSG
@@ -17,18 +20,24 @@ module StaticTracing
     class << self
       def add(tracer)
         raise InvalidTracerError unless tracer < StaticTracing::Tracer::Base
+
         tracers << tracer
       end
 
+      # Enables each tracer, overriding original
+      # method definition with traced one
       def enable!
         tracers.each(&:enable!)
       end
 
+      # Disables each tracer, replacing the method definition
       def disable!
         tracers.each(&:disable!)
       end
 
+      # Clears all tracers
       def clean
+        # FIXME: - actuallly ensure destroyed to avoid memory leaks
         @tracers = []
       end
 

data/lib/ruby-static-tracing/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module StaticTracing
-  VERSION = '0.0.13'
+  # The current version of this gem
+  VERSION = '0.0.14'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-static-tracing
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.14
 platform: ruby
 authors:
 - Dale Hamel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-20 00:00:00.000000000 Z
+date: 2019-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: unmixer
@@ -25,19 +25,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake-compiler
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -53,21 +81,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '11.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: mocha
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="