archive/ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2025-08-15 13:39:04 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

[DOC] Fix grammar errors, typos, and improve readability of trace_point.rb (#12150)

Browse source
This commit is contained in:
Stan Lo 2024-12-13 05:44:15 +08:00 • committed by GitHub
parent ff8570b005
commit 5e8c9b4b28
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
Notes: git 2024-12-12 21:44:34 +00:00 
Merged-By: peterzhu2118 <peter@peterzhu.ca>
1 changed files with 171 additions and 176 deletions
Download patch file Download diff file Expand all files Collapse all files

347
trace_point.rb
View file

@ -1,95 +1,93 @@
# loaded from vm_trace.c # loaded from vm_trace.c
# A class that provides the functionality of Kernel#set_trace_func in a # A class that provides the functionality of Kernel#set_trace_func in a
# nice Object-Oriented API. # well-structured Object-Oriented API.
# #
# == Example # == Example
# #
# We can use TracePoint to gather information specifically for exceptions: # Use TracePoint to gather information specifically for exceptions:
# #
# trace = TracePoint.new(:raise) do |tp| # trace = TracePoint.new(:raise) do |tp|
# p [tp.lineno, tp.event, tp.raised_exception] # p [tp.lineno, tp.event, tp.raised_exception]
# end # end
# #=> #<TracePoint:disabled> # #=> #<TracePoint:disabled>
# #
# trace.enable # trace.enable #=> false
# #=> false
# #
# 0 / 0 # 0 / 0
# #=> [5, :raise, #<ZeroDivisionError: divided by 0>] # #=> [5, :raise, #<ZeroDivisionError: divided by 0>]
# #
# == Events # == Events
# #
# If you don't specify the type of events you want to listen for, # If you don't specify the types of events you want to listen for,
# TracePoint will include all available events. # TracePoint will include all available events.
# #
# *Note* do not depend on current event set, as this list is subject to # *Note:* Do not depend on the current event set, as this list is subject to
# change. Instead, it is recommended you specify the type of events you # change. Instead, it is recommended to specify the types of events you
# want to use. # want to use.
# #
# To filter what is traced, you can pass any of the following as +events+: # To filter what is traced, you can pass any of the following as +events+:
# #
# +:line+:: execute an expression or statement on a new line # +:line+:: Execute an expression or statement on a new line.
# +:class+:: start a class or module definition # +:class+:: Start a class or module definition.
# +:end+:: finish a class or module definition # +:end+:: Finish a class or module definition.
# +:call+:: call a Ruby method # +:call+:: Call a Ruby method.
# +:return+:: return from a Ruby method # +:return+:: Return from a Ruby method.
# +:c_call+:: call a C-language routine # +:c_call+:: Call a C-language routine.
# +:c_return+:: return from a C-language routine # +:c_return+:: Return from a C-language routine.
# +:raise+:: raise an exception # +:raise+:: Raise an exception.
# +:rescue+:: rescue an exception # +:rescue+:: Rescue an exception.
# +:b_call+:: event hook at block entry # +:b_call+:: Event hook at block entry.
# +:b_return+:: event hook at block ending # +:b_return+:: Event hook at block ending.
# +:a_call+:: event hook at all calls (+call+, +b_call+, and +c_call+) # +:a_call+:: Event hook at all calls (+call+, +b_call+, and +c_call+).
# +:a_return+:: event hook at all returns (+return+, +b_return+, and +c_return+) # +:a_return+:: Event hook at all returns (+return+, +b_return+, and +c_return+).
# +:thread_begin+:: event hook at thread beginning # +:thread_begin+:: Event hook at thread beginning.
# +:thread_end+:: event hook at thread ending # +:thread_end+:: Event hook at thread ending.
# +:fiber_switch+:: event hook at fiber switch # +:fiber_switch+:: Event hook at fiber switch.
# +:script_compiled+:: new Ruby code compiled (with +eval+, +load+ or +require+) # +:script_compiled+:: New Ruby code compiled (with +eval+, +load+, or +require+).
# #
class TracePoint class TracePoint
# call-seq: # call-seq:
# TracePoint.new(*events) { |obj| block } -> obj # TracePoint.new(*events) { |tp| block } -> tp
# #
# Returns a new TracePoint object, not enabled by default. # Returns a new TracePoint object, not enabled by default.
# #
# Next, in order to activate the trace, you must use TracePoint#enable # To activate the TracePoint object, use TracePoint#enable:
# #
# trace = TracePoint.new(:call) do |tp| # trace = TracePoint.new(:call) do |tp|
# p [tp.lineno, tp.defined_class, tp.method_id, tp.event] # p [tp.lineno, tp.defined_class, tp.method_id, tp.event]
# end # end
# #=> #<TracePoint:disabled> # #=> #<TracePoint:disabled>
# #
# trace.enable # trace.enable #=> false
# #=> false
# #
# puts "Hello, TracePoint!" # puts "Hello, TracePoint!"
# # ... # # ...
# # [48, IRB::Notifier::AbstractNotifier, :printf, :call] # # [48, IRB::Notifier::AbstractNotifier, :printf, :call]
# # ... # # ...
# #
# When you want to deactivate the trace, you must use TracePoint#disable # To deactivate the trace, use TracePoint#disable.
# #
# trace.disable # trace.disable
# #
# See TracePoint@Events for possible events and more information. # See TracePoint@Events for possible events and more information.
# #
# A block must be given, otherwise an ArgumentError is raised. # A block must be given; otherwise, an ArgumentError is raised.
# #
# If the trace method isn't included in the given events filter, a # If the trace method isn't included in the given events filter, a
# RuntimeError is raised. # RuntimeError is raised.
# #
# TracePoint.trace(:line) do |tp| # TracePoint.trace(:line) do |tp|
# p tp.raised_exception # p tp.raised_exception
# end # end
# #=> RuntimeError: 'raised_exception' not supported by this event # #=> RuntimeError: 'raised_exception' not supported by this event
# #
# If the trace method is called outside block, a RuntimeError is raised. # If the trace method is called outside a block, a RuntimeError is raised.
# #
# TracePoint.trace(:line) do |tp| # TracePoint.trace(:line) do |tp|
# $tp = tp # $tp = tp
# end # end
# $tp.lineno #=> access from outside (RuntimeError) # $tp.lineno #=> access from outside (RuntimeError)
# #
# Access from other threads is also forbidden. # Access from other threads is also forbidden.
# #
@ -98,38 +96,38 @@ class TracePoint
Primitive.tracepoint_new_s(events) Primitive.tracepoint_new_s(events)
end end
# call-seq: # call-seq:
# trace.inspect -> string # trace.inspect -> string
# #
# Return a string containing a human-readable TracePoint # Returns a string containing a human-readable TracePoint
# status. # status.
def inspect def inspect
Primitive.tracepoint_inspect Primitive.tracepoint_inspect
end end
# call-seq: # call-seq:
# TracePoint.stat -> obj # TracePoint.stat -> obj
# #
# Returns internal information of TracePoint. # Returns internal information of TracePoint.
# #
# The contents of the returned value are implementation specific. # The contents of the returned value are implementation-specific
# It may be changed in future. # and may change in the future.
# #
# This method is only for debugging TracePoint itself. # This method is only for debugging TracePoint itself.
def self.stat def self.stat
Primitive.tracepoint_stat_s Primitive.tracepoint_stat_s
end end
# call-seq: # call-seq:
# TracePoint.trace(*events) { |obj| block } -> obj # TracePoint.trace(*events) { |tp| block } -> obj
# #
# A convenience method for TracePoint.new, that activates the trace # A convenience method for TracePoint.new that activates the trace
# automatically. # automatically.
# #
# trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] } # trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
# #=> #<TracePoint:enabled> # #=> #<TracePoint:enabled>
# #
# trace.enabled? #=> true # trace.enabled? #=> true
# #
def self.trace(*events) def self.trace(*events)
Primitive.attr! :use_block Primitive.attr! :use_block
@ -139,14 +137,13 @@ class TracePoint
# call-seq: # call-seq:
# TracePoint.allow_reentry { block } # TracePoint.allow_reentry { block }
# #
# In general, while a TracePoint callback is running, # Generally, while a TracePoint callback is running,
# other registered callbacks are not called to avoid # other registered callbacks are not called to avoid
# confusion by reentrance. # confusion from reentrance.
# This method allows the reentrance in a given block. # This method allows reentrance within a given block.
# This method should be used carefully, otherwise the callback # Use this method carefully to avoid infinite callback invocation.
# can be easily called infinitely.
# #
# If this method is called when the reentrance is already allowed, # If called when reentrance is already allowed,
# it raises a RuntimeError. # it raises a RuntimeError.
# #
# <b>Example:</b> # <b>Example:</b>
@ -155,7 +152,7 @@ class TracePoint
# # --------------- # # ---------------
# #
# line_handler = TracePoint.new(:line) do |tp| # line_handler = TracePoint.new(:line) do |tp|
# next if tp.path != __FILE__ # only work in this file # next if tp.path != __FILE__ # Only works in this file
# puts "Line handler" # puts "Line handler"
# binding.eval("class C; end") # binding.eval("class C; end")
# end.enable # end.enable
@ -167,16 +164,16 @@ class TracePoint
# class B # class B
# end # end
# #
# # This script will print "Class handler" only once: when inside :line # # This script will print "Class handler" only once: when inside the :line
# # handler, all other handlers are ignored # # handler, all other handlers are ignored.
# #
# #
# # With reentry # # With reentry
# # ------------ # # ------------
# #
# line_handler = TracePoint.new(:line) do |tp| # line_handler = TracePoint.new(:line) do |tp|
# next if tp.path != __FILE__ # only work in this file # next if tp.path != __FILE__ # Only works in this file
# next if (__LINE__..__LINE__+3).cover?(tp.lineno) # don't be invoked from itself # next if (__LINE__..__LINE__+3).cover?(tp.lineno) # Prevent infinite calls
# puts "Line handler" # puts "Line handler"
# TracePoint.allow_reentry { binding.eval("class C; end") } # TracePoint.allow_reentry { binding.eval("class C; end") }
# end.enable # end.enable
@ -188,14 +185,15 @@ class TracePoint
# class B # class B
# end # end
# #
# # This wil print "Class handler" twice: inside allow_reentry block in :line # # This will print "Class handler" twice: inside the allow_reentry block in the :line
# # handler, other handlers are enabled. # # handler, other handlers are enabled.
# #
# Note that the example shows the principal effect of the method, but its # Note that the example shows the principal effect of the method, but its
# practical usage is for debugging libraries that sometimes require other libraries # practical usage is for debugging libraries that sometimes require other libraries'
# hooks to not be affected by debugger being inside trace point handling. Precautions # hooks to not be affected by the debugger being inside trace point handling.
# should be taken against infinite recursion in this case (note that we needed to filter # Precautions should be taken against infinite recursion in this case
# out calls by itself from :line handler, otherwise it will call itself infinitely). # (note that we needed to filter out calls by itself from the :line handler,
# otherwise it would call itself infinitely).
# #
def self.allow_reentry def self.allow_reentry
Primitive.attr! :use_block Primitive.attr! :use_block
@ -203,13 +201,13 @@ class TracePoint
end end
# call-seq: # call-seq:
# trace.enable(target: nil, target_line: nil, target_thread: nil) -> true or false # trace.enable(target: nil, target_line: nil, target_thread: nil) -> true or false
# trace.enable(target: nil, target_line: nil, target_thread: :default) { block } -> obj # trace.enable(target: nil, target_line: nil, target_thread: :default) { block } -> obj
# #
# Activates the trace. # Activates the trace.
# #
# Returns +true+ if trace was enabled. # Returns +true+ if the trace was enabled.
# Returns +false+ if trace was disabled. # Returns +false+ if the trace was disabled.
# #
# trace.enabled? #=> false # trace.enabled? #=> false
# trace.enable #=> false (previous state) # trace.enable #=> false (previous state)
@ -218,47 +216,45 @@ class TracePoint
# trace.enable #=> true (previous state) # trace.enable #=> true (previous state)
# # trace is still enabled # # trace is still enabled
# #
# If a block is given, the trace will only be enabled during the block call. # If a block is given, the trace will only be enabled during the block execution.
# If target and target_line are both nil, then target_thread will default # If target and target_line are both nil, then target_thread will default
# to the current thread if a block is given. # to the current thread if a block is given.
# #
# trace.enabled? # trace.enabled? #=> false
# #=> false
# #
# trace.enable do # trace.enable do
# trace.enabled? # trace.enabled?
# # only enabled for this block and thread # # Only enabled for this block and thread
# end # end
# #
# trace.enabled? # trace.enabled? #=> false
# #=> false
# #
# +target+, +target_line+ and +target_thread+ parameters are used to # The +target+, +target_line+, and +target_thread+ parameters are used to
# limit tracing only to specified code objects. +target+ should be a # limit tracing to specified code objects. +target+ should be a
# code object for which RubyVM::InstructionSequence.of will return # code object for which RubyVM::InstructionSequence.of will return
# an instruction sequence. # an instruction sequence.
# #
# t = TracePoint.new(:line) { |tp| p tp } # t = TracePoint.new(:line) { |tp| p tp }
# #
# def m1 # def m1
# p 1 # p 1
# end # end
# #
# def m2 # def m2
# p 2 # p 2
# end # end
# #
# t.enable(target: method(:m1)) # t.enable(target: method(:m1))
# #
# m1 # m1
# # prints #<TracePoint:line test.rb:4 in `m1'> # # Prints #<TracePoint:line test.rb:4 in `m1'>
# m2 # m2
# # prints nothing # # Prints nothing
# #
# Note: You cannot access event hooks within the +enable+ block. # Note: You cannot access event hooks within the +enable+ block.
# #
# trace.enable { p tp.lineno } # trace.enable { p tp.lineno }
# #=> RuntimeError: access from outside # #=> RuntimeError: access from outside
# #
def enable(target: nil, target_line: nil, target_thread: :default) def enable(target: nil, target_line: nil, target_thread: :default)
Primitive.attr! :use_block Primitive.attr! :use_block
@ -266,130 +262,129 @@ class TracePoint
end end
# call-seq: # call-seq:
# trace.disable -> true or false # trace.disable -> true or false
# trace.disable { block } -> obj # trace.disable { block } -> obj
# #
# Deactivates the trace # Deactivates the trace.
# #
# Return true if trace was enabled. # Returns +true+ if the trace was enabled.
# Return false if trace was disabled. # Returns +false+ if the trace was disabled.
# #
# trace.enabled? #=> true # trace.enabled? #=> true
# trace.disable #=> true (previous status) # trace.disable #=> true (previous status)
# trace.enabled? #=> false # trace.enabled? #=> false
# trace.disable #=> false # trace.disable #=> false
# #
# If a block is given, the trace will only be disable within the scope of the # If a block is given, the trace will only be disabled within the scope of the
# block. # block.
# #
# trace.enabled? # trace.enabled? #=> true
# #=> true
# #
# trace.disable do # trace.disable do
# trace.enabled? # trace.enabled?
# # only disabled for this block # # Only disabled for this block
# end # end
# #
# trace.enabled? # trace.enabled? #=> true
# #=> true
# #
# Note: You cannot access event hooks within the block. # Note: You cannot access event hooks within the block.
# #
# trace.disable { p tp.lineno } # trace.disable { p tp.lineno }
# #=> RuntimeError: access from outside # #=> RuntimeError: access from outside
#
def disable def disable
Primitive.attr! :use_block Primitive.attr! :use_block
Primitive.tracepoint_disable_m Primitive.tracepoint_disable_m
end end
# call-seq: # call-seq:
# trace.enabled? -> true or false # trace.enabled? -> true or false
# #
# The current status of the trace # Returns the current status of the trace.
def enabled? def enabled?
Primitive.tracepoint_enabled_p Primitive.tracepoint_enabled_p
end end
# Type of event # Returns the type of event.
# #
# See TracePoint@Events for more information. # See TracePoint@Events for more information.
def event def event
Primitive.tracepoint_attr_event Primitive.tracepoint_attr_event
end end
# Line number of the event # Returns the line number of the event.
def lineno def lineno
Primitive.tracepoint_attr_lineno Primitive.tracepoint_attr_lineno
end end
# Path of the file being run # Returns the path of the file being executed.
def path def path
Primitive.tracepoint_attr_path Primitive.tracepoint_attr_path
end end
# Return the parameters definition of the method or block that the # Returns the parameter definitions of the method or block that the
# current hook belongs to. Format is the same as for Method#parameters # current hook belongs to. The format is the same as for Method#parameters.
def parameters def parameters
Primitive.tracepoint_attr_parameters Primitive.tracepoint_attr_parameters
end end
# Return the name at the definition of the method being called # Returns the name at the definition of the method being called.
def method_id def method_id
Primitive.tracepoint_attr_method_id Primitive.tracepoint_attr_method_id
end end
# Return the called name of the method being called # Returns the called name of the method being called.
def callee_id def callee_id
Primitive.tracepoint_attr_callee_id Primitive.tracepoint_attr_callee_id
end end
# Return class or module of the method being called. # Returns the class or module of the method being called.
# #
# class C; def foo; end; end # class C; def foo; end; end
# trace = TracePoint.new(:call) do |tp| # trace = TracePoint.new(:call) do |tp|
# p tp.defined_class #=> C # p tp.defined_class #=> C
# end.enable do # end.enable do
# C.new.foo # C.new.foo
# end # end
# #
# If method is defined by a module, then that module is returned. # If the method is defined by a module, then that module is returned.
# #
# module M; def foo; end; end # module M; def foo; end; end
# class C; include M; end; # class C; include M; end
# trace = TracePoint.new(:call) do |tp| # trace = TracePoint.new(:call) do |tp|
# p tp.defined_class #=> M # p tp.defined_class #=> M
# end.enable do # end.enable do
# C.new.foo # C.new.foo
# end # end
# #
# <b>Note:</b> #defined_class returns singleton class. # <b>Note:</b> #defined_class returns the singleton class.
# #
# 6th block parameter of Kernel#set_trace_func passes original class # The 6th block parameter of Kernel#set_trace_func passes the original class
# of attached by singleton class. # attached by the singleton class.
# #
# <b>This is a difference between Kernel#set_trace_func and TracePoint.</b> # <b>This is a difference between Kernel#set_trace_func and TracePoint.</b>
# #
# class C; def self.foo; end; end # class C; def self.foo; end; end
# trace = TracePoint.new(:call) do |tp| # trace = TracePoint.new(:call) do |tp|
# p tp.defined_class #=> #<Class:C> # p tp.defined_class #=> #<Class:C>
# end.enable do # end.enable do
# C.foo # C.foo
# end # end
def defined_class def defined_class
Primitive.tracepoint_attr_defined_class Primitive.tracepoint_attr_defined_class
end end
# Return the generated binding object from event. # Returns the generated binding object from the event.
# #
# Note that for +:c_call+ and +:c_return+ events, the method will return # Note that for +:c_call+ and +:c_return+ events, the method returns
# +nil+, since C methods themselves do not have bindings. # +nil+, since C methods themselves do not have bindings.
def binding def binding
Primitive.tracepoint_attr_binding Primitive.tracepoint_attr_binding
end end
# Return the trace object during event # Returns the trace object during the event.
# #
# Same as the following, except it returns the correct object (the method # Similar to the following, but it returns the correct object (the method
# receiver) for +:c_call+ and +:c_return+ events: # receiver) for +:c_call+ and +:c_return+ events:
# #
# trace.binding.eval('self') # trace.binding.eval('self')
@ -397,26 +392,26 @@ class TracePoint
Primitive.tracepoint_attr_self Primitive.tracepoint_attr_self
end end
# Return value from +:return+, +:c_return+, and +:b_return+ event # Returns the return value from +:return+, +:c_return+, and +:b_return+ events.
def return_value def return_value
Primitive.tracepoint_attr_return_value Primitive.tracepoint_attr_return_value
end end
# Value from exception raised on the +:raise+ event, or rescued on the +:rescue+ event. # Returns the exception raised on the +:raise+ event or rescued on the +:rescue+ event.
def raised_exception def raised_exception
Primitive.tracepoint_attr_raised_exception Primitive.tracepoint_attr_raised_exception
end end
# Compiled source code (String) on *eval methods on the +:script_compiled+ event. # Returns the compiled source code (String) from eval methods on the +:script_compiled+ event.
# If loaded from a file, it will return nil. # If loaded from a file, it returns +nil+.
def eval_script def eval_script
Primitive.tracepoint_attr_eval_script Primitive.tracepoint_attr_eval_script
end end
# Compiled instruction sequence represented by a RubyVM::InstructionSequence instance # Returns the compiled instruction sequence represented by a RubyVM::InstructionSequence instance
# on the +:script_compiled+ event. # on the +:script_compiled+ event.
# #
# Note that this method is MRI specific. # Note that this method is CRuby-specific.
def instruction_sequence def instruction_sequence
Primitive.tracepoint_attr_instruction_sequence Primitive.tracepoint_attr_instruction_sequence
end end