From ae455a129e97709d7fd8b11c1e5c3245f4738528 Mon Sep 17 00:00:00 2001 From: zverok Date: Thu, 30 Dec 2021 20:52:42 +0200 Subject: [DOC] Update TracePoint.allow_reentry docs Adjust call-seq to mention block, and add examples and explanations. --- trace_point.rb | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) (limited to 'trace_point.rb') diff --git a/trace_point.rb b/trace_point.rb index d7b9548ecd..82604a59f0 100644 --- a/trace_point.rb +++ b/trace_point.rb @@ -136,7 +136,7 @@ class TracePoint end # call-seq: - # TracePoint.allow_reentry + # TracePoint.allow_reentry { block } # # In general, while a TracePoint callback is running, # other registered callbacks are not called to avoid @@ -147,6 +147,55 @@ class TracePoint # # If this method is called when the reentrance is already allowed, # it raises a RuntimeError. + # + # Example: + # + # # Without reentry + # # --------------- + # + # line_handler = TracePoint.new(:line) do |tp| + # next if tp.path != __FILE__ # only work in this file + # puts "Line handler" + # binding.eval("class C; end") + # end.enable + # + # class_handler = TracePoint.new(:class) do |tp| + # puts "Class handler" + # end.enable + # + # class B + # end + # + # # This script will print "Class handler" only once: when inside :line + # # handler, all other handlers are ignored + # + # + # # With reentry + # # ------------ + # + # line_handler = TracePoint.new(:line) do |tp| + # next if tp.path != __FILE__ # only work in this file + # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # don't be invoked from itself + # puts "Line handler" + # TracePoint.allow_reentry { binding.eval("class C; end") } + # end.enable + # + # class_handler = TracePoint.new(:class) do |tp| + # puts "Class handler" + # end.enable + # + # class B + # end + # + # # This wil print "Class handler" twice: inside allow_reentry block in :line + # # handler, other handlers are enabled. + # + # Note that the example shows the principal effect of the method, but its + # practical usage is for debugging libraries that sometimes require other libraries + # hooks to not be affected by debugger being inside trace point handling. Precautions + # should be taken against infinite recursion in this case (note that we needed to filter + # out calls by itself from :line handler, otherwise it will call itself infinitely). + # def self.allow_reentry Primitive.tracepoint_allow_reentry end -- cgit v1.2.3