• About PLine

PLine is a profiler for Ruby1.9.3 and Ruby1.9.2. PLine profiles each line of Ruby method (method written in Ruby) you specified. Using PLine, you can profile each line of Ruby method easily.

This README document introduces basic functionality of PLine. If you have any questions or comments, please send email to [email protected], or use github.com/soba1104/PLine/issues.

  • License

Same as the license of Ruby runtime.

  • Installation

$gem install pline

Currently, PLine supports Ruby1.9.3 and Ruby1.9.2 only. So, if you want to use PLine, please install PLine under Ruby1.9.3 or Ruby1.9.2 runtime.

  • Usage

############### sample code ############### require ‘pline’

# Target method of profiling def sum(a, b)

a + b

end

# Specify unit of measurement to PLine PLine.show_msec()

# Specify profiling to PLine PLine.profile(self, :sum, true)

1000000.times{|i| sum(i, i)}

################## result ##################

-----------------------------------------

| main.sum: tmp/sample.rb(4 - 6) | |—————————————–| | Line | Time(msec) | Source | |—————————————–| | 4 | 0 | def sum(a, b) | | 5 | 625 | a + b | < You can know that | 6 | 0 | end | ‘a + b’ takes 625 microseconds.

-----------------------------------------

  • Attention

Currently, PLine is alpha version. So, you must not use PLine in critical mission. This section introduces some attentions about PLine.

** Recursive call profiling PLine cannot profile recursive call statements correctly. Profiling results of recursive call statements may become short.

** Block invocation profiling PLine cannot profile exit points of block invocation. Profiling results of exit points of block invocation may become significantly short.

———————— example ———————— # sample code require ‘pline’

def foo

sum = 0
100000.times{|i|
  sum += i
  sum += i
}
sum

end

PLine.profile(self, :foo, true) foo()

# result

----------------------------------------

| main.foo: tmp/test2.rb(3 - 10) | |—————————————-| | Line | Time(usec) | Source | |—————————————-| | 3 | 0 | def foo | | 4 | 2 | sum = 0 | | 5 | 2 | 100000.times{|i| | | 6 | 81190 | sum = i | | 7 | 3 | sum = i | <= this | 8 | 0 | } | | 9 | 1 | sum | | 10 | 0 | end |

----------------------------------------

** Using together with other profiler PLine rewrites RUBY_EVENT_LINE event to RUBY_EVENT_END event. So, when you use PLine, above events become incompatible. You should not use PLine together with other profilers which use above events.

  • PLine APIs

This section introduces PLine APIs.

** A API of specifying profiling

  • PLine.profile(object, method_id, singleton_p = false)

Specify profiling to PLine. When singleton_p argument(third argument) is false, PLine searches object#method_id (instance method). Otherwise, PLine searches object.method_id (singleton_method).

** APIs of specifying output

  • PLine.output=(io)

Specify output io object. Default output of PLine is STDERR.

  • PLine.show_sec()

Specify sec as the unit of measurement.

  • PLine.show_msec()

Specify millisec as the unit of measurement.

  • PLine.show_usec()

Specify microsec as the unit of measurement. Microsec is the default unit of measurement.

  • PLine.show_nsec()

Specify nanosec as the unit of measurement.