timify 0.0.6 → 1.0.0

data/lib/timify.rb

@@ -1,199 +1,153 @@
-###############################################################
-# Calculates the time running from one location to another inside your code. More info: https://github.com/MarioRuiz/timify/
+# frozen_string_literal: true
+
+require_relative "timify/version"
+require_relative "timify/span"
+require_relative "timify/trace"
+require_relative "timify/registry"
+require_relative "timify/recording"
+require_relative "timify/report"
+
+# Measures elapsed time between points in Ruby code.
+#
+# {#measure} blocks nest. A parent span's +inclusive+ time is the whole block,
+# and its +secs+ (self time) is what the children did not already take.
+# {#add} marks the time since the previous mark on this thread. Intervals use
+# a monotonic clock. {#totals} still reports +started+ and +finished+ as Time
+# objects.
+#
+# Each thread has its own cursor and span stack. Totals are shared and guarded
+# by a mutex, so two threads can mark the same timer. +total_time+ is the sum
+# of self time and can exceed +wall_time+ when threads overlap.
 #
-#   attr_accessor:
-#     min_time_to_show: minimum time to show the elapsed time when calling 'add' method
-#     show: print out results on screen
-#	  status: (default :on) You can set :on or :off the status so it will counting the time or not
+# {.enabled} is a process-wide switch. When it is +false+, every timer is a
+# no-op: {#add} and {#measure} record nothing, and {#initialize} does not
+# print. The default comes from +TIMIFY_DISABLE+ (+1+, +true+, or +on+, case
+# insensitive). Setting {.enabled=} overrides that for the rest of the process.
 #
-#   attr_reader:
-#     name: name given for the Timify instance
-#     initial_time: when the instance was created
-#     total: total time elapsed
-#     max_time_spent: maximum time measured for this instance
-###############################################################
+# @example Time a few nested steps without printing
+#   timer = Timify.new(:create_user, show: false)
+#   timer.measure(:request) do
+#     timer.measure(:database) { :saved }
+#     timer.add(:mail)
+#   end
+#   timer.totals
 class Timify
-  attr_accessor :min_time_to_show, :show, :status
-  attr_reader :name, :total, :initial_time, :max_time_spent
-
-  ###############################################################
-  # input:
-  #   name: name for the instance
-  #   min_time_to_show: minimum time to show the elapsed time when calling 'add' method
-  #   show: print out results on screen
-  #
-  # examples:
-  #   t = Timify.new :create_user
-  #   t.show = false
-  #   $tim = Timify.new :dbprocess, show:false, min_time_to_show: 0.5
-  ###############################################################
-  def initialize(name, min_time_to_show: 0, show: true)
-    @name=name
-    @min_time_to_show=min_time_to_show
-    @show=show
-    @initial_time=Time.new
-    @max_time_spent=0
-    @timify_prev=@initial_time
-    @location_prev=nil
-    @timify={}
-    @timify_by_label={}
-    @timify_by_range={}
-    @count={}
-    @total=0
-    puts "<#{@name}> Timify init:<#{@initial_time}>. Location: #{caller[0].scan(/(.+):in\s/).join}"
-  end
-
-  ###############################################################
-  # Adds a new point to count the time elapsed.
-  # It will count from the last 'add' call or Timify creation in case of the first 'add'.
-  #
-  #   input:
-  #     label: (optional) In case supplied it will summarize all the ones with the same label
-  #
-  #   output: (float)
-  #     time elapsed in seconds
-  #
-  #   examples:
-  #     t=Timify.new :example
-  #     t.add; run_sqls; t.add :database
-  #     t.add
-  #     #some processes
-  #     t.add
-  #     #some processes
-  #     send_email_alert if t.add > 0.2
-  #     #some processes
-  #     do_log(t.totals[:message]) if t.add > 0.5
-  ###############################################################
-  def add(*label)
-	return 0 if @status==:off
-    if !label.empty?
-      label=label[0]
-    else
-      label=""
-    end
+  class << self
+    # Process-wide recording switch. When +false+, every timer is a no-op.
+    # Defaults from +TIMIFY_DISABLE+ when the class loads; {.enabled=} overrides
+    # that for the rest of the process.
+    #
+    # @return [Boolean]
+    attr_accessor :enabled
 
-    time_now=Time.new
-    time_spent=(time_now-@timify_prev).to_f
-    @total=(time_now-@initial_time).to_f
-    new_max=false
-    location=caller[0].scan(/(.+):in\s/).join
-    if time_spent > @max_time_spent then
-      new_max = true
-      @max_time_spent = time_spent
-    end
-    @timify[location]=@timify[location].to_f+time_spent
-    @count[location]=@count[location].to_i+1
-    if !label.empty?
-      @timify_by_label[label]=@timify_by_label[label].to_f+time_spent
-      @count[label]=@count[label].to_i+1
-    end
-    if !@location_prev.nil?
-      @timify_by_range["#{@location_prev} - #{location}"]=@timify_by_range["#{@location_prev} - #{location}"].to_f + time_spent
-      @count["#{@location_prev} - #{location}"]=@count["#{@location_prev} - #{location}"].to_i+1
+    # @return [Boolean] whether recording is currently enabled
+    def enabled?
+      !!@enabled
     end
 
+    # Whether +TIMIFY_DISABLE+ is set to a disabling value (+1+, +true+, or
+    # +on+, case insensitive). Used as the default for {.enabled} when the
+    # class loads.
+    #
+    # @return [Boolean]
+    def env_disabled?
+      value = ENV["TIMIFY_DISABLE"]
+      return false if value.nil?
 
-    if @total > 0
-      percent=((@timify[location]/@total)*100).round(0)
-    else
-      percent=0
-    end
-    if time_spent>=@min_time_to_show
-      if @show
-        puts "<#{@name}>#{"<#{label}>" if !label.empty?}#{"(New Max)" if new_max}: #{location} (#{percent}%): #{@total.round(2)}; #{time_spent.round(2)}"
-      end
+      %w[1 true on].include?(value.to_s.strip.downcase)
     end
-    @timify_prev=time_now
-    @location_prev=location
-    return time_spent
   end
 
+  self.enabled = !env_disabled?
+
+  # @return [Object] name given when the timer was created
+  attr_reader :name
+
+  # @return [Float] self time recorded so far, excluding paused time
+  attr_reader :total
 
-  ###############################################################
-  # returns all data for this instance
+  # @return [Time] wall-clock time when the timer was created or last {#reset}
+  attr_reader :initial_time
+
+  # @return [Float] longest single self-time segment since creation or {#reset}
+  attr_reader :max_time_spent
+
+  # @return [Symbol] +:on+ while the timer is recording, +:off+ while it is paused
+  attr_reader :status
+
+  # Minimum segment length, in seconds, required before {#add} or {#measure}
+  # prints. Shorter segments are still recorded. Defaults to +0+.
+  #
+  # @return [Numeric]
+  attr_accessor :min_time_to_show
+
+  # When +false+, the timer stays silent. Segments are still recorded.
+  # Defaults to +true+.
   #
-  #   input:
-  #     json: (boolean) in case of true the output will be in json format instead of a hash
+  # @return [Boolean]
+  attr_accessor :show
+
+  # Where printed lines are sent. An object that responds to +puts+ is written
+  # with +puts+. An object that responds to +info+ and not +puts+, such as a
+  # Logger, is written with +info+. Defaults to +$stdout+.
   #
-  #   output: (Hash or json string)
-  #     name: (String) name given for this instance
-  #     total_time: (float) total elapsed time from initialization to last 'add' call
-  #     started: (Time)
-  #     finished: (Time)
-  #     message: (String) a printable friendly message giving all information
-  #     locations, labels, ranges: (Hash) the resultant hash contains:
-  #       secs: (float) number of seconds
-  #       percent: (integer) percentage in reference to the total time
-  #       count: (integer) number of times
-  #     locations: (Hash) All summary data by location where was called
-  #     labels: (Hash) All summary data by label given on 'add' method
-  #     ranges: (Hash) All summary data by ranges where was called, from last 'add' call to current 'add' call
-  ###############################################################
-  def totals(json: false)
-  	return {} if @status==:off
-    require 'json' if json
-    output={
-        name: @name,
-        total_time: @total.to_f,
-        started: @initial_time,
-        finished: @timify_prev,
-        locations: {},
-        labels: {},
-        ranges: {}
-    }
-    message="\n\nTotal time <#{@name}>:#{@total.to_f.round(2)}"
-    message+="\nTotal time by location:\n"
-    @timify.each {|location, secs|
-      if @total==0 then
-        percent=0
-      else
-        percent=(secs*100/(@total).to_f).round(0)
-      end
-      message+= "\t#{location}: #{secs.round(2)} (#{percent}%) ##{@count[location]}\n"
-      output[:locations][location]={
-          secs: secs,
-          percent: percent,
-          count: @count[location]
-      }
-    }
-    if !@timify_by_label.empty?
-      message+= "\nTotal time by label:\n"
-      @timify_by_label.each {|label, secs|
-        if @total==0 then
-          percent=0
-        else
-          percent=(secs*100/(@total).to_f).round(0)
-        end
-        message+= "\t#{label}: #{secs.round(2)} (#{percent}%) ##{@count[label]}\n"
-        output[:labels][label]={
-            secs: secs,
-            percent: percent,
-            count: @count[label]
-        }
-      }
-    end
+  # @return [#puts, #info]
+  attr_accessor :output
 
-    if !@timify_by_range.empty?
-      message+= "\nTotal time by range:\n"
-      @timify_by_range.each {|range, secs|
-        if @total==0 then
-          percent=0
-        else
-          percent=(secs*100/(@total).to_f).round(0)
-        end
-        message+= "\t#{range}: #{secs.round(2)} (#{percent}%) ##{@count[range]}\n"
-        output[:ranges][range]={
-            secs: secs,
-            percent: percent,
-            count: @count[range]
-        }
-      }
-    end
+  # @param name [Object] name included in reports and printed lines
+  # @param min_time_to_show [Numeric] shortest segment that should be printed
+  # @param show [Boolean] whether to print the init line, segments, and summaries
+  # @param output [#puts, #info] destination for printed lines
+  def initialize(name, min_time_to_show: 0, show: true, output: $stdout)
+    @name = name
+    @min_time_to_show = min_time_to_show
+    @show = show
+    @output = output
+    @mutex = Mutex.new
+    @generation = 0
+    @slow_handlers = []
+    @share_handlers = []
+    @resume_at = nil
+    @pause_started = nil
+    @paused_monotonic = 0.0
+    reset
+    emit("<#{@name}> Timify init:<#{@initial_time}>. Location: #{caller_location}") if self.class.enabled?
+  end
+
+  # Creates a timer, yields it, and returns it after the block finishes.
+  # The block's return value is not returned; use {#measure} on the yielded
+  # timer when you need that value, or use {.trace} to keep both. If the block
+  # raises, the exception propagates and the timer is not returned.
+  #
+  # @param name [Object]
+  # @param options [Hash] keyword arguments accepted by {#initialize}
+  # @yield [timer] the new timer
+  # @yieldparam timer [Timify]
+  # @return [Timify]
+  # @raise [ArgumentError] when no block is given
+  def self.measure(name, **options)
+    raise ArgumentError, "measure requires a block" unless block_given?
+
+    timer = new(name, **options)
+    yield timer
+    timer
+  end
+
+  # Creates a timer, yields it, and returns a {Trace} with the block's value
+  # and the timer. If the block raises, the exception propagates and no
+  # {Trace} is returned.
+  #
+  # @param name [Object]
+  # @param options [Hash] keyword arguments accepted by {#initialize}
+  # @yield [timer] the new timer
+  # @yieldparam timer [Timify]
+  # @return [Timify::Trace]
+  # @raise [ArgumentError] when no block is given
+  def self.trace(name, **options)
+    raise ArgumentError, "trace requires a block" unless block_given?
 
-    message+= "\n\n"
-    output[:message]=message
-    puts message if @show
-    output=output.to_json if json
-    return output
+    timer = new(name, **options)
+    value = yield timer
+    Trace.new(value: value, timer: timer)
   end
 end

metadata

@@ -1,34 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: timify
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Mario Ruiz
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Easily calculate the time running (elapsed time) from one location to
-  another inside your code and reports statistics. It helps you improve your code
-  and find out which part of your code is consuming more time.
+description: Calculate elapsed time from one location to another inside your code
+  and report statistics. It helps you improve your code and find out which part of
+  your code is consuming more time.
 email: marioruizs@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 files:
 - ".yardopts"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/timify.rb
+- lib/timify/recording.rb
+- lib/timify/registry.rb
+- lib/timify/report.rb
+- lib/timify/span.rb
+- lib/timify/trace.rb
+- lib/timify/version.rb
 homepage: https://github.com/MarioRuiz/timify
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  changelog_uri: https://github.com/MarioRuiz/timify/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/MarioRuiz/timify
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -36,16 +45,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.6
 specification_version: 4
-summary: Easily calculate the time running (elapsed time) from one location to another
-  inside your code and reports statistics.
+summary: Calculate elapsed time from one location to another inside your code and
+  report statistics.
 test_files: []