puppet-retrospec 0.7.0 → 0.7.2

data/vendor/gems/puppet-3.7.3/lib/puppet/util/inline_docs.rb

@@ -0,0 +1,26 @@
+module Puppet::Util::InlineDocs
+  def self.included(klass)
+    klass.send(:include, InstanceMethods)
+    klass.extend ClassMethods
+  end
+
+  module ClassMethods
+    attr_accessor :use_docs
+    def associates_doc
+      self.use_docs = true
+    end
+  end
+
+  module InstanceMethods
+    attr_writer :doc
+
+    def doc
+      @doc ||= ""
+    end
+
+    # don't fetch lexer comment by default
+    def use_docs
+      self.class.use_docs
+    end
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/util/instance_loader.rb

@@ -0,0 +1,81 @@
+require 'puppet/util/autoload'
+require 'puppet/util'
+
+# A module that can easily autoload things for us.  Uses an instance
+# of Puppet::Util::Autoload
+module Puppet::Util::InstanceLoader
+  include Puppet::Util
+
+  # Are we instance-loading this type?
+  def instance_loading?(type)
+    defined?(@autoloaders) and @autoloaders.include?(type.intern)
+  end
+
+  # Define a new type of autoloading.
+  def instance_load(type, path, options = {})
+    @autoloaders ||= {}
+    @instances ||= {}
+    type = type.intern
+    @instances[type] = {}
+    @autoloaders[type] = Puppet::Util::Autoload.new(self, path, options)
+
+    # Now define our new simple methods
+    unless respond_to?(type)
+      meta_def(type) do |name|
+        loaded_instance(type, name)
+      end
+    end
+  end
+
+  # Return a list of the names of all instances
+  def loaded_instances(type)
+    @instances[type].keys
+  end
+
+  # Collect the docs for all of our instances.
+  def instance_docs(type)
+    docs = ""
+
+    # Load all instances.
+    instance_loader(type).loadall
+
+    # Use this method so they all get loaded
+    loaded_instances(type).sort { |a,b| a.to_s <=> b.to_s }.each do |name|
+      mod = self.loaded_instance(name)
+      docs << "#{name}\n#{"-" * name.to_s.length}\n"
+
+      docs << Puppet::Util::Docs.scrub(mod.doc) << "\n\n"
+    end
+
+    docs
+  end
+
+  # Return the instance hash for our type.
+  def instance_hash(type)
+    @instances[type.intern]
+  end
+
+  # Return the Autoload object for a given type.
+  def instance_loader(type)
+    @autoloaders[type.intern]
+  end
+
+  # Retrieve an alread-loaded instance, or attempt to load our instance.
+  def loaded_instance(type, name)
+    name = name.intern
+    return nil unless instances = instance_hash(type)
+    unless instances.include? name
+      if instance_loader(type).load(name)
+        unless instances.include? name
+          Puppet.warning(
+            "Loaded #{type} file for #{name} but #{type} was not defined"
+          )
+          return nil
+        end
+      else
+        return nil
+      end
+    end
+    instances[name]
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/util/instrumentation.rb

@@ -0,0 +1,152 @@
+require 'puppet'
+require 'puppet/util/classgen'
+require 'puppet/util/instance_loader'
+
+class Puppet::Util::Instrumentation
+  extend Puppet::Util::ClassGen
+  extend Puppet::Util::InstanceLoader
+
+  # we're using a ruby lazy autoloader to prevent a loop when requiring listeners
+  # since this class sets up an indirection which is also used in Puppet::Indirector::Indirection
+  # which is used to setup indirections...
+  autoload :Listener, 'puppet/util/instrumentation/listener'
+  autoload :Data, 'puppet/util/instrumentation/data'
+
+  # Set up autoloading and retrieving of instrumentation listeners.
+  instance_load :listener, 'puppet/util/instrumentation/listeners'
+
+  class << self
+    attr_accessor :listeners, :listeners_of
+  end
+
+  # instrumentation layer
+
+  # Triggers an instrumentation
+  #
+  # Call this method around the instrumentation point
+  #   Puppet::Util::Instrumentation.instrument(:my_long_computation) do
+  #     ... a long computation
+  #   end
+  #
+  # This will send an event to all the listeners of "my_long_computation".
+  # Note: this method uses ruby yield directive to call the instrumented code.
+  # It is usually way slower than calling start and stop directly around the instrumented code.
+  # For high traffic code path, it is thus advisable to not use this method.
+  def self.instrument(label, data = {})
+    id = self.start(label, data)
+    yield
+  ensure
+    self.stop(label, id, data)
+  end
+
+  # Triggers a "start" instrumentation event
+  #
+  # Important note:
+  #  For proper use, the data hash instance used for start should also
+  #  be used when calling stop. The idea is to use the current scope
+  #  where start is called to retain a reference to 'data' so that it is possible
+  #  to send it back to stop.
+  #  This way listeners can match start and stop events more easily.
+  def self.start(label, data)
+    data[:started] = Time.now
+    publish(label, :start, data)
+    data[:id] = next_id
+  end
+
+  # Triggers a "stop" instrumentation event
+  def self.stop(label, id, data)
+    data[:finished] = Time.now
+    publish(label, :stop, data)
+  end
+
+  def self.publish(label, event, data)
+    each_listener(label) do |k,l|
+      l.notify(label, event, data)
+    end
+  end
+
+  def self.listeners
+    @listeners.values
+  end
+
+  def self.each_listener(label)
+    @listeners_of[label] ||= @listeners.select do |k,l|
+      l.listen_to?(label)
+    end.each do |l|
+      yield l
+    end
+  end
+
+  # Adds a new listener
+  #
+  # Usage:
+  #   Puppet::Util::Instrumentation.new_listener(:my_instrumentation, pattern) do
+  #
+  #     def notify(label, data)
+  #       ... do something for data...
+  #     end
+  #   end
+  #
+  # It is possible to use a "pattern". The listener will be notified only
+  # if the pattern match the label of the event.
+  # The pattern can be a symbol, a string or a regex.
+  # If no pattern is provided, then the listener will be called for every events
+  def self.new_listener(name, options = {}, &block)
+    Puppet.debug "new listener called #{name}"
+    name = name.intern
+    listener = genclass(name, :hash => instance_hash(:listener), :block => block)
+    listener.send(:define_method, :name) do
+      name
+    end
+    subscribe(listener.new, options[:label_pattern], options[:event])
+  end
+
+  def self.subscribe(listener, label_pattern, event)
+    raise "Listener #{listener.name} is already subscribed" if @listeners.include?(listener.name)
+    Puppet.debug "registering instrumentation listener #{listener.name}"
+    @listeners[listener.name] = Listener.new(listener, label_pattern, event)
+    listener.subscribed if listener.respond_to?(:subscribed)
+    rehash
+  end
+
+  def self.unsubscribe(listener)
+    Puppet.warning("#{listener.name} hasn't been registered but asked to be unregistered") unless @listeners.include?(listener.name)
+    Puppet.info "unregistering instrumentation listener #{listener.name}"
+    @listeners.delete(listener.name)
+    listener.unsubscribed if listener.respond_to?(:unsubscribed)
+    rehash
+  end
+
+  def self.init
+    # let's init our probe indirection
+    require 'puppet/util/instrumentation/indirection_probe'
+    @listeners ||= {}
+    @listeners_of ||= {}
+    instance_loader(:listener).loadall
+  end
+
+  def self.clear
+    @listeners = {}
+    @listeners_of = {}
+    @id = 0
+  end
+
+  def self.[](key)
+    @listeners[key.intern]
+  end
+
+  def self.[]=(key, value)
+    @listeners[key.intern] = value
+    rehash
+  end
+
+  private
+
+  def self.rehash
+    @listeners_of = {}
+  end
+
+  def self.next_id
+    @id = (@id || 0) + 1
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/util/instrumentation/data.rb

@@ -0,0 +1,46 @@
+require 'puppet/indirector'
+require 'puppet/util/instrumentation'
+
+# This is just a transport class to be used through the instrumentation_data
+# indirection. All the data resides in the real underlying listeners which this
+# class delegates to.
+class Puppet::Util::Instrumentation::Data
+  extend Puppet::Indirector
+
+  indirects :instrumentation_data, :terminus_class => :local
+
+  attr_reader :listener
+
+  def initialize(listener_name)
+    @listener = Puppet::Util::Instrumentation[listener_name]
+    raise "Listener #{listener_name} wasn't registered" unless @listener
+  end
+
+  def name
+    @listener.name
+  end
+
+  def to_data_hash
+    { :name => name }.merge(@listener.respond_to?(:data) ? @listener.data : {})
+  end
+
+  def to_pson_data_hash
+    {
+      'document_type' => "Puppet::Util::Instrumentation::Data",
+      'data' => to_data_hash,
+    }
+  end
+
+  def to_pson(*args)
+    to_pson_data_hash.to_pson(*args)
+  end
+
+  def self.from_data_hash(data)
+    data
+  end
+
+  def self.from_pson(data)
+    Puppet.deprecation_warning("from_pson is being removed in favour of from_data_hash.")
+    data
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/util/instrumentation/indirection_probe.rb

@@ -0,0 +1,41 @@
+require 'puppet/indirector'
+require 'puppet/util/instrumentation'
+
+# We need to use a class other than Probe for the indirector because
+# the Indirection class might declare some probes, and this would be a huge unbreakable
+# dependency cycle.
+class Puppet::Util::Instrumentation::IndirectionProbe
+  extend Puppet::Indirector
+
+  indirects :instrumentation_probe, :terminus_class => :local
+
+  attr_reader :probe_name
+
+  def initialize(probe_name)
+    @probe_name = probe_name
+  end
+
+  def to_data_hash
+    { :name => probe_name }
+  end
+
+  def to_pson_data_hash
+    {
+      :document_type => "Puppet::Util::Instrumentation::IndirectionProbe",
+      :data => to_data_hash,
+    }
+  end
+
+  def to_pson(*args)
+    to_pson_data_hash.to_pson(*args)
+  end
+
+  def self.from_data_hash(data)
+    self.new(data["name"])
+  end
+
+  def self.from_pson(data)
+    Puppet.deprecation_warning("from_pson is being removed in favour of from_data_hash.")
+    self.from_data_hash(data)
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/util/instrumentation/instrumentable.rb

@@ -0,0 +1,136 @@
+require 'puppet/util/instrumentation'
+
+# This is the central point of all declared probes.
+# Every class needed to declare probes should include this module
+# and declare the methods that are subject to instrumentation:
+#
+#   class MyClass
+#     extend Puppet::Util::Instrumentation::Instrumentable
+#
+#     probe :mymethod
+#
+#     def mymethod
+#       ... this is code to be instrumented ...
+#     end
+#   end
+module Puppet::Util::Instrumentation::Instrumentable
+  INSTRUMENTED_CLASSES = {}
+
+  attr_reader :probes
+
+  class Probe
+    attr_reader :klass, :method, :label, :data
+
+    def initialize(method, klass, options = {})
+      @method = method
+      @klass = klass
+
+      @label = options[:label] || method
+      @data = options[:data] || {}
+    end
+
+    def enable
+      raise "Probe already enabled" if enabled?
+
+      # We're forced to perform this copy because in the class_eval'uated
+      # block below @method would be evaluated in the class context. It's better
+      # to close on locally-scoped variables than to resort to complex namespacing
+      # to get access to the probe instance variables.
+      method = @method; label = @label; data = @data
+      klass.class_eval {
+        alias_method("instrumented_#{method}", method)
+        define_method(method) do |*args|
+          id = nil
+          instrumentation_data = nil
+          begin
+            instrumentation_label = label.respond_to?(:call) ? label.call(self, args) : label
+            instrumentation_data = data.respond_to?(:call) ? data.call(self, args) : data
+            id = Puppet::Util::Instrumentation.start(instrumentation_label, instrumentation_data)
+            send("instrumented_#{method}".to_sym, *args)
+          ensure
+            Puppet::Util::Instrumentation.stop(instrumentation_label, id, instrumentation_data || {})
+          end
+        end
+      }
+      @enabled = true
+    end
+
+    def disable
+      raise "Probe is not enabled" unless enabled?
+
+      # For the same reason as in #enable, we're forced to do a local
+      # copy
+      method = @method
+      klass.class_eval do
+        alias_method(method, "instrumented_#{method}")
+        remove_method("instrumented_#{method}".to_sym)
+      end
+      @enabled = false
+    end
+
+    def enabled?
+      !!@enabled
+    end
+  end
+
+  # Declares a new probe
+  #
+  # It is possible to pass several options that will be later on evaluated
+  # and sent to the instrumentation layer.
+  #
+  # label::
+  #   this can either be a static symbol/string or a block. If it's a block
+  #   this one will be evaluated on every call of the instrumented method and
+  #   should return a string or a symbol
+  #
+  # data::
+  #   this can be a hash or a block. If it's a block this one will be evaluated
+  #   on every call of the instrumented method and should return a hash.
+  #
+  #Example:
+  #
+  #   class MyClass
+  #     extend Instrumentable
+  #
+  #     probe :mymethod, :data => Proc.new { |args|  { :data => args[1] } }, :label => Proc.new { |args| args[0] }
+  #
+  #     def mymethod(name, options)
+  #     end
+  #
+  #   end
+  #
+  def probe(method, options = {})
+    (@probes ||= []) << Probe.new(method, self, options)
+    INSTRUMENTED_CLASSES[self] = @probes
+  end
+
+  def self.probes
+    @probes
+  end
+
+  def self.probe_names
+    probe_names = []
+    each_probe { |probe| probe_names << "#{probe.klass}.#{probe.method}" }
+    probe_names
+  end
+
+  def self.enable_probes
+    each_probe { |probe| probe.enable }
+  end
+
+  def self.disable_probes
+    each_probe { |probe| probe.disable }
+  end
+
+  def self.clear_probes
+    INSTRUMENTED_CLASSES.clear
+    nil # do not leak our probes to the exterior world
+  end
+
+  def self.each_probe
+    INSTRUMENTED_CLASSES.each_key do |klass|
+      klass.probes.each { |probe| yield probe }
+    end
+    nil # do not leak our probes to the exterior world
+  end
+end