im-lost 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3508c022462842507ce749828e2c74c4db9e9097496e68cedc758018017cb5
-  data.tar.gz: 93ac54d98ae6474d4f7144b116cf0e2784c88babf57ff592a317b463caa7ee13
+  metadata.gz: 38b1a5b729438621357238f12f64f1d397ee56e18174c2cc1ec60067dd0ab15e
+  data.tar.gz: 157e15bcf3c9e9539467347e9cac31b5ed40adf9953bc6ab28dab6d163907288
 SHA512:
-  metadata.gz: 4d45f27c98a6ed477ce4e696f4c41286ca24c105de1668889bf64fc0d57d3947e04c026b40fa7f5f79e2ce5016fcc8327e3c9a8b20a1e6ae0561900efae4f5f3
-  data.tar.gz: 1502147a826924c39988f9272d62e3c0274dc8cdb961f25c405a229cf6273142579ad136af1972c06874d13af110486b79db45907c219bd3082a91cd507220ab
+  metadata.gz: 8ad0cc365f318ef0113d6f099618204b11ecd547a84d525893cc2691a59a5159594c8606de34bad9268867751708cf98f03102a1b0feefbab6cefa41c2436449
+  data.tar.gz: eb0a3abf3fffc2273593741c880c9aa5b4461d2b14877e324834216327d9ec427a80eaf2b075381df601b920477b50c8b95190c34ae9cc73fb3d1b25407aa4a1

data/README.md

@@ -19,15 +19,16 @@ File.open('test.txt', 'w') do |file|
     file.puts(:world!)
   end
 end
+
 # output will look like
 #  > IO#<<(?)
-#    /projects/test.rb:1
+#    /examples/test.rb:1
 #  > IO#write(*)
-#    /projects/test.rb:1
+#    /examples/test.rb:1
 #  > IO#puts(*)
-#    /projects/test.rb:2
+#    /examples/test.rb:2
 #  > IO#write(*)
-#    /projects/test.rb:2
+#    /examples/test.rb:2
 ```
 
 When you need to know if exceptions are raised and handled you can use `ImLost.trace_exceptions`:
@@ -38,16 +39,17 @@ ImLost.trace_exceptions do
 rescue SystemCallError
   raise('something went wrong!')
 end
+
 # output will look like
 #  x Errno::EEXIST: File exists @ rb_sysopen - /
-#    /projects/test.rb:2
+#    /examples/test.rb:2
 #  ! Errno::EEXIST: File exists @ rb_sysopen - /
-#    /projects/test.rb:3
+#    /examples/test.rb:3
 #  x RuntimeError: something went wrong!
-#    /projects/test.rb:4
+#    /examples/test.rb:4
 ```
 
-When you like to know if and when a code point is reached, `ImLost.here` will help:
+When you like to know if a code point is reached, `ImLost.here` will help:
 
 ```ruby
 ImLost.here
@@ -92,7 +94,6 @@ class Foo
   def bar = :bar
 end
 
-ImLost.trace_results = true
 ImLost.trace(Foo)
 
 my_foo = Foo.create(value: :foo!)
@@ -109,47 +110,55 @@ ImLost.vars(my_foo)
 
 # output will look like
 #   > Foo.create(:foo!)
-#     /projects/foo.rb:25
+#     /examples/foo.rb:24
 #   > Foo.new(*)
-#     /projects/foo.rb:6
+#     /examples/foo.rb:6
 #   < Foo.new(*)
-#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#     /examples/foo.rb:6
+#     = #<Foo:0x00000001006448c0 @value=:foo!>
 #   < Foo.create(:foo!)
-#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#     /examples/foo.rb:24
+#     = #<Foo:0x00000001006448c0 @value=:foo!>
 #   > Foo#foo(1, *[], :none, **{}, &nil)
-#     /projects/foo.rb:28
+#     /examples/foo.rb:27
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   < Foo#foo(1, *[], :none, **{}, &nil)
+#     /examples/foo.rb:27
 #     = "1-none-[]-{}-bar"
-#   = /projects/foo.rb:29
-#     instance variables:
-#     @value: "1-none-[]-{}-bar"
+#   * /examples/foo.rb:28
+#     > instance variables
+#       @value: "1-none-[]-{}-bar"
 #   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
-#     /projects/foo.rb:31
+#     /examples/foo.rb:30
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   < Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
+#     /examples/foo.rb:30
 #     = "2-some-[a,b,c]-{:name=>:value}-bar"
-#   = /projects/foo.rb:32
-#     instance variables:
-#     @value: "2-some-[a,b,c]-{:name=>:value}-bar"
-#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
-#     /projects/foo.rb:34
+#   * /examples/foo.rb:31
+#     > instance variables
+#       @value: "2-some-[a,b,c]-{:name=>:value}-bar"
+#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100641d28 /examples/foo.rb:33>)
+#     /examples/foo.rb:33
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   3--[]-{}-bar
-#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100641d28 /examples/foo.rb:33>)
+#     /examples/foo.rb:33
 #     = nil
-#   = /projects/foo.rb:35
-#     instance variables:
-#     @value: "3--[]-{}-bar"
+#   * /examples/foo.rb:34
+#     > instance variables
+#       @value: "3--[]-{}-bar"
 ```
 
 See [examples dir](./examples) for more…

data/examples/foo.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../lib/im-lost'
+require 'im-lost'
 
 class Foo
   def self.create(value:) = new(value)
@@ -19,7 +19,6 @@ class Foo
   def bar = :bar
 end
 
-ImLost.trace_results = true
 ImLost.trace(Foo)
 
 my_foo = Foo.create(value: :foo!)
@@ -36,44 +35,52 @@ ImLost.vars(my_foo)
 
 # output will look like
 #   > Foo.create(:foo!)
-#     /projects/foo.rb:25
+#     /examples/foo.rb:24
 #   > Foo.new(*)
-#     /projects/foo.rb:6
+#     /examples/foo.rb:6
 #   < Foo.new(*)
-#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#     /examples/foo.rb:6
+#     = #<Foo:0x00000001006448c0 @value=:foo!>
 #   < Foo.create(:foo!)
-#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#     /examples/foo.rb:24
+#     = #<Foo:0x00000001006448c0 @value=:foo!>
 #   > Foo#foo(1, *[], :none, **{}, &nil)
-#     /projects/foo.rb:28
+#     /examples/foo.rb:27
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   < Foo#foo(1, *[], :none, **{}, &nil)
+#     /examples/foo.rb:27
 #     = "1-none-[]-{}-bar"
-#   = /projects/foo.rb:29
-#     instance variables:
-#     @value: "1-none-[]-{}-bar"
+#   * /examples/foo.rb:28
+#     > instance variables
+#       @value: "1-none-[]-{}-bar"
 #   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
-#     /projects/foo.rb:31
+#     /examples/foo.rb:30
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   < Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
+#     /examples/foo.rb:30
 #     = "2-some-[a,b,c]-{:name=>:value}-bar"
-#   = /projects/foo.rb:32
-#     instance variables:
-#     @value: "2-some-[a,b,c]-{:name=>:value}-bar"
-#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
-#     /projects/foo.rb:34
+#   * /examples/foo.rb:31
+#     > instance variables
+#       @value: "2-some-[a,b,c]-{:name=>:value}-bar"
+#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100641d28 /examples/foo.rb:33>)
+#     /examples/foo.rb:33
 #   > Foo#bar()
-#     /projects/foo.rb:15
+#     /examples/foo.rb:15
 #   < Foo#bar()
+#     /examples/foo.rb:15
 #     = :bar
 #   3--[]-{}-bar
-#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100641d28 /examples/foo.rb:33>)
+#     /examples/foo.rb:33
 #     = nil
-#   = /projects/foo.rb:35
-#     instance variables:
-#     @value: "3--[]-{}-bar"
+#   * /examples/foo.rb:34
+#     > instance variables
+#       @value: "3--[]-{}-bar"

data/examples/kernel_calls.rb

@@ -9,7 +9,6 @@ INFO
 
 require 'im-lost'
 
-ImLost.trace_results = true
 ImLost.trace(Kernel, Object, Module, Class, self) do
   puts '=' * 79
   pp Class.new

data/examples/timer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+puts <<~INFO
+
+  This is an example how to use named and anonymous timers.
+
+INFO
+
+require_relative '../lib/im-lost'
+
+puts 'Create a named timer:'
+ImLost.timer.create(:first)
+
+puts 'Create an anonymous timer:'
+second = ImLost.timer.create
+
+sleep(0.5) # or whatever
+
+puts 'print runtime for named timer:'
+ImLost.timer[:first]
+
+puts 'print runtime for anonymous timer:'
+ImLost.timer[second]
+
+puts 'delete a named timer'
+ImLost.timer.delete(:first)
+
+puts 'delete an anonymous timer'
+ImLost.timer.delete(second)

data/lib/im-lost/version.rb

@@ -2,5 +2,5 @@
 
 module ImLost
   # The version number of the gem.
-  VERSION = '1.0.2'
+  VERSION = '1.2.0'
 end

data/lib/im-lost.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+#
 # If you have overlooked something again and don't really understand what your
 # code is doing. If you have to maintain this application but can't really find
 # your way around and certainly can't track down that stupid error. If you feel
@@ -25,9 +26,10 @@ module ImLost
 
     #
     # The output device used to write information.
-    # This should be an `IO` device or any other object responding to `#puts`.
+    # This should be an `IO` device or any other object responding to `#<<`
+    # like a Logger.
     #
-    # `$stderr` is configured by default.
+    # `STDERR` is configured by default.
     #
     # @example Write to a file
     #   ImLost.output = File.new('./trace', 'w')
@@ -49,10 +51,21 @@ module ImLost
     attr_reader :output
 
     def output=(value)
-      return @output = value if value.respond_to?(:puts)
-      raise(ArgumentError, "invalid output device - #{value.inspect}")
+      return @output = value if defined?(value.<<)
+      raise(
+        NoMethodError,
+        "undefined method `<<' for an instance of #{
+          Kernel.instance_method(:class).bind(value).call
+        }"
+      )
     end
 
+    #
+    # @return [TimerStore] the timer store used to estimate the runtime of
+    #   your code
+    #
+    attr_reader :timer
+
     #
     # Enables/disables tracing of method calls.
     # This is enabled by default.
@@ -79,13 +92,14 @@ module ImLost
     #   rescue SystemCallError
     #     raise('something went wrong!')
     #   end
+    #
     #   # output will look like
     #   #   x Errno::EEXIST: File exists @ rb_sysopen - /
-    #   #   /projects/test.rb:2
+    #   #     /examples/test.rb:2
     #   #   ! Errno::EEXIST: File exists @ rb_sysopen - /
-    #   #   /projects/test.rb:3
+    #   #     /examples/test.rb:3
     #   #   x RuntimeError: something went wrong!
-    #   #   /projects/test.rb:4
+    #   #     /examples/test.rb:4
     #
     # @param with_locations [Boolean] wheter the locations should be included
     #   into the exception trace information
@@ -105,7 +119,7 @@ module ImLost
 
     #
     # Enables/disables tracing of returned valuess of method calls.
-    # This is disabled by default.
+    # This is enabled by default.
     #
     # @attribute [r] trace_results
     # @return [Boolean] whether return values will be traced
@@ -123,33 +137,33 @@ module ImLost
     #
     # Print the call location conditionally.
     #
-    # @example simply print location
+    # @example Print current location
     #   ImLost.here
     #
-    # @example print location when instance variable is empty
+    # @example Print current location when instance variable is empty
     #   ImLost.here(@name.empty?)
     #
-    # @example print location when instance variable is nil or empty
+    # @example Print current location when instance variable is nil or empty
     #   ImLost.here { @name.nil? || @name.empty? }
     #
     # @overload here
-    #   Prints the caller location.
+    #   Prints the call location.
     #   @return [true]
     #
     # @overload here(test)
-    #   Prints the caller location when given argument is truthy.
+    #   Prints the call location when given argument is truthy.
     #   @param test [Object]
     #   @return [Object] test
     #
     # @overload here
-    #   Prints the caller location when given block returns a truthy result.
+    #   Prints the call location when given block returns a truthy result.
     #   @yield When the block returns a truthy result the location will be print
     #   @yieldreturn [Object] return result
     #
     def here(test = true)
       return test if !test || (block_given? && !(test = yield))
       loc = Kernel.caller_locations(1, 1)[0]
-      @output.puts(": #{loc.path}:#{loc.lineno}")
+      @output << "* #{loc.path}:#{loc.lineno}\n"
       test
     end
 
@@ -158,36 +172,36 @@ module ImLost
     #
     # The given arguments can be any object instance or module or class.
     #
-    # @example trace method calls of an instance variable for a while
+    # @example Trace method calls of an instance variable for a while
     #   ImLost.trace(@file)
     #   # ...
     #   ImLost.untrace(@file)
     #
-    # @example temporary trace method calls
+    # @example Temporary trace method calls
     #   File.open('test.txt', 'w') do |file|
     #     ImLost.trace(file) do
     #       file << 'hello '
     #       file.puts(:world!)
     #     end
     #   end
-    #   output will look like
-    #     > IO#<<(?)
-    #       /projects/test.rb:1
-    #     > IO#write(*)
-    #       /projects/test.rb:1
-    #     > IO#puts(*)
-    #       /projects/test.rb:2
-    #     > IO#write(*)
-    #       /projects/test.rb:2
+    #
+    #   # output will look like
+    #   #   > IO#<<(?)
+    #   #     /examples/test.rb:1
+    #   #   > IO#write(*)
+    #   #     /examples/test.rb:1
+    #   #   > IO#puts(*)
+    #   #     /examples/test.rb:2
+    #   #   > IO#write(*)
+    #   #     /examples/test.rb:2
     #
     # @overload trace(*args)
     #   @param args [[Object]] one or more objects to be traced
-    #   @return [[Object]] the traced object(s)
+    #   @return [Array<Object>] the traced object(s)
     #   Start tracing the given objects.
     #   @see untrace
     #   @see untrace_all!
     #
-    #
     # @overload trace(*args)
     #   @param args [[Object]] one or more objects to be traced
     #   @yieldparam args [Object] the traced object(s)
@@ -201,30 +215,37 @@ module ImLost
       args.size == 1 ? _trace_b(args[0], &block) : _trace_all_b(args, &block)
     end
 
+    #
+    # Test if a given object is currently traced.
+    #
+    # @param arg [Object] object to be tested
+    # @return [Boolean] wheter the object is beeing traced
+    #
+    def traced?(obj) = @trace.key?(obj)
+
     #
     # Stop tracing objects.
     #
-    # @example trace some objects for some code lines
-    #   traced_vars = ImLost.trace(@file, @client)
+    # @example Trace some objects for some code lines
+    #   traced_obj = ImLost.trace(@file, @client)
     #   # ...
-    #   ImLost.untrace(*traced_vars)
+    #   ImLost.untrace(*traced_obj)
     #
     # @see trace
     #
-    # @param args [[Object]] one or more objects which should not longer be
+    # @param args [[]Object]] one or more objects which should not longer be
     #   traced
-    # @return [[Object]] the object(s) which are not longer be traced
+    # @return [Array<Object>] the object(s) which are not longer be traced
     # @return [nil] when none of the objects was traced before
     #
     def untrace(*args)
-      ret = args.filter_map { @trace.delete(_1.__id__) ? _1 : nil }
-      args.size == 1 ? ret[0] : ret
+      args = args.filter_map { @trace.delete(_1) }
+      args.size < 2 ? args[0] : args
     end
 
     #
-    # Stop tracing any object.
-    # (When you are really lost and just like to stop tracing of all your
-    #   objects.)
+    # Stop tracing any object. When you are really lost and just like to stop
+    # tracing of all your objects.
     #
     # @see trace
     #
@@ -236,171 +257,396 @@ module ImLost
     end
 
     #
-    # Inspect internal variables.
+    # Inspect internal variables of a given object.
+    #
+    # @note The dedictaed handling of `Fiber` is platform dependend!
+    #
+    # @example Inspect current instance variables
+    #   @a = 22
+    #   b = 20
+    #   c = @a + b
+    #   ImLost.vars(self)
+    #   # => print value of `@a`
+    #
+    # @example Inspect local variables
+    #   @a = 22
+    #   b = 20
+    #   c = @a + b
+    #   ImLost.vars(binding)
+    #   # => print values of `b` and 'c'
+    #
+    # @example Inspect a thread's variables
+    #   th = Thread.new { th[:var1] += 20 }
+    #   th[:var1] = 22
+    #   ImLost.vars(th)
+    #   # => print value of `var1`
+    #   th.join
+    #   ImLost.vars(th)
     #
-    # @overload vars(binding)
-    #   Inspect local variables of given Binding.
-    #   @param binding [Binding] which local variables should be print
-    #   @return [self] itself
+    # @example Inspect the current fiber's storage
+    #   Fiber[:var1] = 22
+    #   Fiber[:var2] = 20
+    #   Fiber[:var3] = Fiber[:var1] + Fiber[:var2]
+    #   ImLost.vars(Fiber.current)
     #
-    # @overload vars(object)
-    #   Inspect instance variables of given object.
-    #   @param object [Object] which instance variables should be print
-    #   @return [Object] the given object
+    # When the given object is
+    #
+    # - a `Binding` it prints the local variables of the binding
+    # - a `Thread` it prints the fiber-local and thread variables
+    # - the current `Fiber` it prints the fibers' storage
+    #
+    # Be aware that only the current fiber can be inspected.
+    #
+    # When the given object can not be inspected it prints an error message.
+    #
+    # @param object [Object] which instance variables should be print
+    # @return [Object] the given object
     #
     def vars(object)
-      traced = @trace.delete(object.__id__)
-      return _local_vars(object) if object.is_a?(Binding)
-      return unless object.respond_to?(:instance_variables)
-      _vars(object, Kernel.caller_locations(1, 1)[0])
+      out = Out.new
+      traced = @trace.delete(object)
+      return _local_vars(out, object) if Binding === object
+      location = Kernel.caller_locations(1, 1)[0]
+      out << "* #{location.path}:#{location.lineno}"
+      return _thread_vars(out, object) if Thread === object
+      return _fiber_vars(out, object) if @fiber_supported && Fiber === object
+      return _instance_vars(out, object) if defined?(object.instance_variables)
+      out << '  !!! unable to retrieve vars'
+      object
     ensure
       @trace[traced] = traced if traced
+      out.flush(@output)
     end
 
-    protected
+    private
 
-    def as_sig(prefix, info, args)
-      args = args.join(', ')
-      case info.self
-      when Class, Module
-        "#{prefix} #{info.self}.#{info.method_id}(#{args})"
-      else
-        "#{prefix} #{info.defined_class}##{info.method_id}(#{args})"
-      end
+    def _can_trace?(arg)
+      (id = arg.__id__) != __id__ && id != @output.__id__
     end
 
-    private
-
     def _trace(arg)
-      id = arg.__id__
-      @trace[id] = id if __id__ != id && @output.__id__ != id
+      @trace[arg] = arg if _can_trace?(arg)
       arg
     end
 
     def _trace_all(args)
-      args.each do |arg|
-        arg = arg.__id__
-        @trace[arg] = arg if __id__ != arg && @output.__id__ != arg
-      end
+      args.each { |arg| @trace[arg] = arg if _can_trace?(arg) }
       args
     end
 
     def _trace_b(arg)
-      id = arg.__id__
-      return yield(arg) if __id__ == id || @output.__id__ == id
+      return yield(arg) if @trace.key?(arg) || !_can_trace?(arg)
       begin
-        @trace[id] = id
+        @trace[arg] = arg
         yield(arg)
       ensure
-        @trace.delete(id) if id
+        @trace.delete(arg)
       end
     end
 
     def _trace_all_b(args)
-      ids =
+      temp =
         args.filter_map do |arg|
-          arg = arg.__id__
-          @trace[arg] = arg if __id__ != arg && @output.__id__ != arg
+          @trace[arg] = arg if !@trace.key?(arg) && _can_trace?(arg)
         end
       yield(args)
     ensure
-      ids.each { @trace.delete(_1) }
+      temp.each { @trace.delete(_1) }
+    end
+
+    def _local_vars(out, binding)
+      out << "* #{binding.source_location.join(':')}"
+      out.vars('local variables', binding.local_variables) do |name|
+        binding.local_variable_get(name)
+      end
+      binding
+    end
+
+    def _thread_vars(out, thread)
+      out << "  #{_thread_identifier(thread)}"
+      flv = thread.keys
+      out.vars('fiber-local variables', flv) { thread[_1] } unless flv.empty?
+      out.vars('thread variables', thread.thread_variables) do |name|
+        thread.thread_variable_get(name)
+      end
+      thread
     end
 
-    def _vars(obj, location)
-      @output.puts("= #{location.path}:#{location.lineno}")
-      vars = obj.instance_variables
-      if vars.empty?
-        @output.puts('  <no instance variables defined>')
+    def _fiber_vars(out, fiber)
+      if Fiber.current == fiber
+        storage = fiber.storage || {}
+        out.vars('fiber storage', storage.keys) { storage[_1] }
       else
-        @output.puts('  instance variables:')
-        vars.sort!.each do |name|
-          @output.puts("  #{name}: #{obj.instance_variable_get(name).inspect}")
+        out << '  !!! given Fiber is not the current Fiber' <<
+          "      #{fiber.inspect}"
+      end
+      fiber
+    end
+
+    def _instance_vars(out, object)
+      out.vars('instance variables', object.instance_variables) do |n|
+        object.instance_variable_get(n)
+      end
+      object
+    end
+
+    def _thread_identifier(thread)
+      "#{THREAD_STATE[thread.status] || thread.status} Thread #{
+        if defined?(thread.native_thread_id)
+          thread.native_thread_id
+        else
+          thread.__id__
+        end
+      } #{thread.name}".rstrip
+    end
+  end
+
+  #
+  # A store to create and register timers you can use to estimate the runtime of
+  # some code.
+  #
+  # All timers are identified by an unique ID or a name.
+  #
+  # @example Use a named timer
+  #   ImLost.timer.create('my_test')
+  #
+  #   # ...your code here...
+  #
+  #   ImLost.timer['my_test']
+  #   # => prints the timer name, this location and runtime so far
+  #
+  #   # ...more code here...
+  #
+  #   ImLost.timer['my_test']
+  #   # => prints the timer name, this location and runtime since the timer was created
+  #
+  #   ImLost.timer.delete('my_test')
+  #   # the timer with name 'my_test' is not longer valid now
+  #
+  #
+  # @example Use an anonymous timer
+  #   tmr = ImLost.timer.create
+  #
+  #   # ...your code here...
+  #
+  #   ImLost.timer[tmr]
+  #   # => prints the timer ID, this location and runtime so far
+  #
+  #   # ...more code here...
+  #
+  #   ImLost.timer[tmr]
+  #   # => prints the timer ID, this location and runtime since the timer was created
+  #
+  #   ImLost.timer.delete(tmr)
+  #   # the timer with the ID `tmr` is not longer valid now
+  #
+  # @see ImLost.timer
+  #
+  class TimerStore
+    if defined?(Process::CLOCK_MONOTONIC)
+      # @return [Float] current time
+      def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    else
+      # @return [Float] current time
+      def self.now = ::Time.now
+    end
+
+    # @attribute [r] count
+    # @return [Integer] the number of registered timers
+    def count = ids.size
+
+    # @attribute [r] empty?
+    # @return [Boolean] wheter the timer store is empty or not
+    def empty? = ids.empty?
+
+    # @attribute [r] ids
+    # @return [Array<Integer>] IDs of all registered timers
+    def ids = (@ll.keys.keep_if { _1.is_a?(Integer) })
+
+    #
+    # Create and register a new named or anonymous timer.
+    # It print the ID or name of the created timer and includes the location.
+    #
+    # @param name [#to_s] optional timer name
+    # @return [Integer] timer ID
+    #
+    def create(name = nil)
+      timer = []
+      @ll[id = timer.__id__] = timer
+      name ? @ll[name = name.to_s] = timer : name = id
+      @cb[name, Kernel.caller_locations(1, 1)[0]]
+      timer << name << self.class.now
+      id
+    end
+
+    #
+    # Delete and unregister timers.
+    #
+    # @param id_or_names [Array<Integer, #to_s>] the IDs or the names
+    # @return [nil]
+    #
+    def delete(*id_or_names)
+      id_or_names.flatten.each do |id|
+        if id.is_a?(Integer)
+          del = @ll.delete(id)
+          @ll.delete(del[0]) if del
+        else
+          del = @ll.delete(id.to_s)
+          @ll.delete(del.__id__) if del
         end
       end
-      obj
+      nil
     end
 
-    def _local_vars(binding)
-      @output.puts("= #{binding.source_location.join(':')}")
-      vars = binding.local_variables
-      if vars.empty?
-        @output.puts('  <no local variables>')
+    #
+    # Print the ID or name and the runtime since a timer was created.
+    # It includes the location.
+    #
+    # @param id_or_name [Integer, #to_s] the identifier or the name of the timer
+    # @return [Integer] timer ID
+    # @raise [ArgumentError] when the given id or name is not a registered timer
+    #   identifier or name
+    #
+    def [](id_or_name)
+      time = self.class.now
+      timer = @ll[id_or_name.is_a?(Integer) ? id_or_name : id_or_name.to_s]
+      raise(ArgumentError, "not a timer - #{id_or_name.inspect}") unless timer
+      @cb[timer[0], Kernel.caller_locations(1, 1)[0], time - timer[1]]
+      timer.__id__
+    end
+
+    #
+    # Print the ID or name and the runtime of all active timers.
+    # It includes the location.
+    #
+    # @return [nil]
+    #
+    def all
+      now = self.class.now
+      loc = Kernel.caller_locations(1, 1)[0]
+      @ll.values.uniq.reverse_each { |name, start| @cb[name, loc, now - start] }
+      nil
+    end
+
+    # @!visibility private
+    def initialize(&block)
+      @cb = block
+      @ll = {}
+    end
+  end
+
+  class Out
+    def initialize(*lines) = (@lines = lines)
+    def <<(str) = @lines << str
+    def location(loc) = @lines << "  #{loc.path}:#{loc.lineno}"
+    def flush(dev) = dev << (@lines << nil).join("\n")
+
+    def sig(prefix, info, args)
+      args = args.join(', ')
+      @lines << case info.self
+      when Class, Module
+        "#{prefix} #{info.self}.#{info.method_id}(#{args})"
       else
-        @output.puts('  local variables:')
-        vars.sort!.each do |name|
-          @output.puts("  #{name}: #{binding.local_variable_get(name).inspect}")
-        end
+        "#{prefix} #{info.defined_class}##{info.method_id}(#{args})"
       end
-      self
+    end
+
+    def vars(kind, names)
+      return @lines << "  <no #{kind} defined>" if names.empty?
+      @lines << "  > #{kind}"
+      names.sort!.each { @lines << "    #{_1}: #{yield(_1).inspect}" }
     end
   end
+  private_constant :Out
 
   ARG_SIG = { rest: '*', keyrest: '**', block: '&' }.compare_by_identity.freeze
   NO_NAME = { :* => 1, :** => 1, :& => 1 }.compare_by_identity.freeze
-  private_constant :ARG_SIG, :NO_NAME
+  THREAD_STATE = {
+    false => 'terminated',
+    nil => 'aborted'
+  }.compare_by_identity.freeze
+  private_constant :ARG_SIG, :NO_NAME, :THREAD_STATE
 
   @trace = {}.compare_by_identity
-  @caller_locations = true
-  @output = $stderr.respond_to?(:puts) ? $stderr : STDERR
+  @caller_locations = @exception_locations = true
+  @output = STDERR
+
+  @timer = TimerStore.new { |title, location, time| @output << <<~TIMER_MSG }
+    T #{title}: #{time ? "#{time} sec." : 'created'}
+      #{location.path}:#{location.lineno}
+  TIMER_MSG
+  TimerStore.private_class_method(:new)
 
   @trace_calls = [
     TracePoint.new(:c_call) do |tp|
-      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
-      @output.puts(as_sig('>', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' }))
-      @output.puts("  #{tp.path}:#{tp.lineno}") if @caller_locations
+      next if !@trace.key?(tp.self) || tp.path == __FILE__
+      out = Out.new
+      out.sig('>', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' })
+      out.location(tp) if @caller_locations
+      out.flush(@output)
     end,
     TracePoint.new(:call) do |tp|
-      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
+      next if !@trace.key?(tp.self) || tp.path == __FILE__
       ctx = tp.binding
-      @output.puts(
-        as_sig(
-          '>',
-          tp,
-          tp.parameters.map do |kind, name|
-            next name if NO_NAME.key?(name)
-            "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
-          end
-        )
+      out = Out.new
+      out.sig(
+        '>',
+        tp,
+        tp.parameters.map do |kind, name|
+          next name if NO_NAME.key?(name)
+          "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
+        end
       )
-      next unless @caller_locations
-      loc = ctx.eval('caller_locations(4,1)')[0]
-      @output.puts("  #{loc.path}:#{loc.lineno}")
+      out.location(ctx.eval('caller_locations(4,1)')[0]) if @caller_locations
+      out.flush(@output)
     end
   ]
 
   @trace_results = [
     TracePoint.new(:c_return) do |tp|
-      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
-      @output.puts(as_sig('<', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' }))
-      @output.puts("  = #{tp.return_value.inspect}")
+      next if !@trace.key?(tp.self) || tp.path == __FILE__
+      out = Out.new
+      out.sig('<', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' })
+      out.location(tp) if @caller_locations
+      out << "  = #{tp.return_value.inspect}"
+      out.flush(@output)
     end,
     TracePoint.new(:return) do |tp|
-      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
+      next if !@trace.key?(tp.self) || tp.path == __FILE__
       ctx = tp.binding
-      @output.puts(
-        as_sig(
-          '<',
-          tp,
-          tp.parameters.map do |kind, name|
-            next name if %i[* ** &].include?(name)
-            "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
-          end
-        )
+      out = Out.new
+      out.sig(
+        '<',
+        tp,
+        tp.parameters.map do |kind, name|
+          next name if NO_NAME.key?(name)
+          "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
+        end
       )
-      @output.puts("  = #{tp.return_value.inspect}")
+      out.location(ctx.eval('caller_locations(4,1)')[0]) if @caller_locations
+      out << "  = #{tp.return_value.inspect}"
+      out.flush(@output)
     end
   ]
 
-  supported = RUBY_VERSION >= '3.3.0' ? %i[raise rescue] : %i[raise]
+  supported = RUBY_VERSION.to_f < 3.3 ? %i[raise] : %i[raise rescue]
   @trace_exceptions =
     TracePoint.new(*supported) do |tp|
-      ex = tp.raised_exception.inspect
-      @output.puts(
-        "#{tp.event == :raise ? 'x' : '!'} #{ex[0] == '#' ? ex[2..-2] : ex}"
-      )
-      @output.puts("  #{tp.path}:#{tp.lineno}") if @exception_locations
+      ex = tp.raised_exception
+      mark, parent = tp.event == :rescue ? ['!', ex.cause] : 'x'
+      ex = ex.inspect
+      out = Out.new("#{mark} #{ex[0] == '#' ? ex[2..-2] : ex}")
+      while parent
+        ex = parent.inspect
+        out << "  [#{ex[0] == '#' ? ex[2..-2] : ex}]"
+        parent = parent.cause
+      end
+      out.location(tp) if @exception_locations
+      out.flush(@output)
     end
 
-  self.trace_calls = true
+  @fiber_supported =
+    !!(defined?(Fiber.current) && defined?(Fiber.current.storage))
+
+  self.trace_calls = self.trace_results = true
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: im-lost
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-13 00:00:00.000000000 Z
+date: 2024-06-18 00:00:00.000000000 Z
 dependencies: []
 description: |
   If you have overlooked something again and don't really understand what
@@ -30,6 +30,7 @@ files:
 - README.md
 - examples/foo.rb
 - examples/kernel_calls.rb
+- examples/timer.rb
 - lib/im-lost.rb
 - lib/im-lost/version.rb
 - lib/im_lost.rb
@@ -56,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
+rubygems_version: 3.5.13
 signing_key:
 specification_version: 4
 summary: Your debugging helper.