ruby-prof 0.12.1 → 0.12.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (109) hide show
  1. data/CHANGES +5 -1
  2. data/Rakefile +25 -7
  3. data/bin/ruby-prof +2 -2
  4. data/doc/LICENSE.html +155 -0
  5. data/doc/README_rdoc.html +640 -0
  6. data/doc/Rack.html +167 -0
  7. data/doc/Rack/RubyProf.html +319 -0
  8. data/doc/RubyProf.html +999 -0
  9. data/doc/RubyProf/AbstractPrinter.html +580 -0
  10. data/doc/RubyProf/AggregateCallInfo.html +570 -0
  11. data/doc/RubyProf/CallInfo.html +512 -0
  12. data/doc/RubyProf/CallInfoPrinter.html +190 -0
  13. data/doc/RubyProf/CallInfoVisitor.html +332 -0
  14. data/doc/RubyProf/CallStackPrinter.html +1597 -0
  15. data/doc/RubyProf/CallTreePrinter.html +413 -0
  16. data/doc/RubyProf/Cmd.html +669 -0
  17. data/doc/RubyProf/DotPrinter.html +312 -0
  18. data/doc/RubyProf/FlatPrinter.html +229 -0
  19. data/doc/RubyProf/FlatPrinterWithLineNumbers.html +267 -0
  20. data/doc/RubyProf/GraphHtmlPrinter.html +622 -0
  21. data/doc/RubyProf/GraphPrinter.html +209 -0
  22. data/doc/RubyProf/MethodInfo.html +713 -0
  23. data/doc/RubyProf/MultiPrinter.html +407 -0
  24. data/doc/RubyProf/Profile.html +821 -0
  25. data/doc/RubyProf/ProfileTask.html +532 -0
  26. data/doc/RubyProf/Test.html +578 -0
  27. data/doc/RubyProf/Thread.html +262 -0
  28. data/doc/created.rid +31 -0
  29. data/doc/examples/flat_txt.html +191 -0
  30. data/doc/examples/graph_txt.html +305 -0
  31. data/doc/images/add.png +0 -0
  32. data/doc/images/brick.png +0 -0
  33. data/doc/images/brick_link.png +0 -0
  34. data/doc/images/bug.png +0 -0
  35. data/doc/images/bullet_black.png +0 -0
  36. data/doc/images/bullet_toggle_minus.png +0 -0
  37. data/doc/images/bullet_toggle_plus.png +0 -0
  38. data/doc/images/date.png +0 -0
  39. data/doc/images/delete.png +0 -0
  40. data/doc/images/find.png +0 -0
  41. data/doc/images/loadingAnimation.gif +0 -0
  42. data/doc/images/macFFBgHack.png +0 -0
  43. data/doc/images/package.png +0 -0
  44. data/doc/images/page_green.png +0 -0
  45. data/doc/images/page_white_text.png +0 -0
  46. data/doc/images/page_white_width.png +0 -0
  47. data/doc/images/plugin.png +0 -0
  48. data/doc/images/ruby.png +0 -0
  49. data/doc/images/tag_blue.png +0 -0
  50. data/doc/images/tag_green.png +0 -0
  51. data/doc/images/transparent.png +0 -0
  52. data/doc/images/wrench.png +0 -0
  53. data/doc/images/wrench_orange.png +0 -0
  54. data/doc/images/zoom.png +0 -0
  55. data/doc/index.html +639 -0
  56. data/doc/js/darkfish.js +153 -0
  57. data/doc/js/jquery.js +18 -0
  58. data/doc/js/navigation.js +142 -0
  59. data/doc/js/search.js +94 -0
  60. data/doc/js/search_index.js +1 -0
  61. data/doc/js/searcher.js +228 -0
  62. data/doc/rdoc.css +543 -0
  63. data/doc/table_of_contents.html +462 -0
  64. data/examples/empty.png +0 -0
  65. data/examples/minus.png +0 -0
  66. data/examples/plus.png +0 -0
  67. data/ext/ruby_prof/extconf.rb +5 -1
  68. data/ext/ruby_prof/rp_call_info.c +1 -1
  69. data/ext/ruby_prof/rp_measure_gc_time.c +6 -10
  70. data/ext/ruby_prof/rp_measure_memory.c +0 -1
  71. data/ext/ruby_prof/rp_stack.c +0 -5
  72. data/ext/ruby_prof/vc/ruby_prof_18.vcxproj +0 -2
  73. data/ext/ruby_prof/vc/ruby_prof_19.vcxproj +1 -3
  74. data/ext/ruby_prof/vc/ruby_prof_20.vcxproj +1 -3
  75. data/ext/ruby_prof/version.h +2 -2
  76. data/lib/ruby-prof/compatibility.rb +8 -3
  77. data/lib/ruby-prof/images/empty.png +0 -0
  78. data/lib/ruby-prof/images/minus.png +0 -0
  79. data/lib/ruby-prof/images/plus.png +0 -0
  80. data/lib/ruby-prof/task.rb +0 -0
  81. data/ruby-prof.gemspec +2 -1
  82. data/test/aggregate_test.rb +0 -0
  83. data/test/basic_test.rb +0 -0
  84. data/test/duplicate_names_test.rb +0 -0
  85. data/test/dynamic_method_test.rb +8 -1
  86. data/test/enumerable_test.rb +0 -0
  87. data/test/exceptions_test.rb +0 -0
  88. data/test/exclude_threads_test.rb +0 -0
  89. data/test/exec_test.rb +0 -0
  90. data/test/line_number_test.rb +0 -0
  91. data/test/measure_gc_runs_test.rb +4 -1
  92. data/test/measure_gc_time_test.rb +10 -3
  93. data/test/measure_memory_test.rb +3 -8
  94. data/test/measure_process_time_test.rb +10 -4
  95. data/test/method_elimination_test.rb +1 -2
  96. data/test/module_test.rb +0 -0
  97. data/test/multi_printer_test.rb +5 -6
  98. data/test/no_method_class_test.rb +0 -0
  99. data/test/pause_resume_test.rb +6 -8
  100. data/test/printers_test.rb +0 -0
  101. data/test/recursive_test.rb +0 -0
  102. data/test/singleton_test.rb +0 -0
  103. data/test/stack_printer_test.rb +8 -5
  104. data/test/stack_test.rb +0 -0
  105. data/test/start_stop_test.rb +0 -0
  106. data/test/test_helper.rb +16 -4
  107. data/test/thread_test.rb +0 -0
  108. data/test/unique_call_path_test.rb +0 -0
  109. metadata +90 -17
data/doc/examples/graph_txt.html ADDED
@@ -0,0 +1,305 @@
1
+ <!DOCTYPE html>
2
+
3
+ <html>
4
+ <head>
5
+ <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
6
+
7
+ <title>graph - ruby-prof</title>
8
+
9
+ <link type="text/css" media="screen" href="../rdoc.css" rel="stylesheet">
10
+
11
+ <script type="text/javascript">
12
+ var rdoc_rel_prefix = "../";
13
+ </script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
16
+ <script type="text/javascript" charset="utf-8" src="../js/navigation.js"></script>
17
+ <script type="text/javascript" charset="utf-8" src="../js/search_index.js"></script>
18
+ <script type="text/javascript" charset="utf-8" src="../js/search.js"></script>
19
+ <script type="text/javascript" charset="utf-8" src="../js/searcher.js"></script>
20
+ <script type="text/javascript" charset="utf-8" src="../js/darkfish.js"></script>
21
+
22
+
23
+ <body class="file">
24
+ <nav id="metadata">
25
+ <nav id="home-section" class="section">
26
+ <h3 class="section-header">
27
+ <a href="../index.html">Home</a>
28
+ <a href="../table_of_contents.html#classes">Classes</a>
29
+ <a href="../table_of_contents.html#methods">Methods</a>
30
+ </h3>
31
+ </nav>
32
+
33
+
34
+ <nav id="search-section" class="section project-section" class="initially-hidden">
35
+ <form action="#" method="get" accept-charset="utf-8">
36
+ <h3 class="section-header">
37
+ <input type="text" name="search" placeholder="Search" id="search-field"
38
+ title="Type to search, Up and Down to navigate, Enter to load">
39
+ </h3>
40
+ </form>
41
+
42
+ <ul id="search-results" class="initially-hidden"></ul>
43
+ </nav>
44
+
45
+
46
+ <div id="project-metadata">
47
+ <nav id="fileindex-section" class="section project-section">
48
+ <h3 class="section-header">Pages</h3>
49
+
50
+ <ul>
51
+
52
+ <li class="file"><a href="../LICENSE.html">LICENSE</a>
53
+
54
+ <li class="file"><a href="../README_rdoc.html">README</a>
55
+
56
+ <li class="file"><a href="../examples/flat_txt.html">flat</a>
57
+
58
+ <li class="file"><a href="../examples/graph_txt.html">graph</a>
59
+
60
+ </ul>
61
+ </nav>
62
+
63
+ <nav id="classindex-section" class="section project-section">
64
+ <h3 class="section-header">Class and Module Index</h3>
65
+
66
+ <ul class="link-list">
67
+
68
+ <li><a href="../RubyProf.html">RubyProf</a>
69
+
70
+ <li><a href="../RubyProf/AbstractPrinter.html">RubyProf::AbstractPrinter</a>
71
+
72
+ <li><a href="../RubyProf/AggregateCallInfo.html">RubyProf::AggregateCallInfo</a>
73
+
74
+ <li><a href="../RubyProf/CallInfo.html">RubyProf::CallInfo</a>
75
+
76
+ <li><a href="../RubyProf/CallInfoPrinter.html">RubyProf::CallInfoPrinter</a>
77
+
78
+ <li><a href="../RubyProf/CallInfoVisitor.html">RubyProf::CallInfoVisitor</a>
79
+
80
+ <li><a href="../RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>
81
+
82
+ <li><a href="../RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>
83
+
84
+ <li><a href="../RubyProf/Cmd.html">RubyProf::Cmd</a>
85
+
86
+ <li><a href="../RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>
87
+
88
+ <li><a href="../RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>
89
+
90
+ <li><a href="../RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
91
+
92
+ <li><a href="../RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
93
+
94
+ <li><a href="../RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
95
+
96
+ <li><a href="../RubyProf/MethodInfo.html">RubyProf::MethodInfo</a>
97
+
98
+ <li><a href="../RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>
99
+
100
+ <li><a href="../RubyProf/Profile.html">RubyProf::Profile</a>
101
+
102
+ <li><a href="../RubyProf/ProfileTask.html">RubyProf::ProfileTask</a>
103
+
104
+ <li><a href="../RubyProf/Test.html">RubyProf::Test</a>
105
+
106
+ <li><a href="../RubyProf/Thread.html">RubyProf::Thread</a>
107
+
108
+ <li><a href="../Rack.html">Rack</a>
109
+
110
+ <li><a href="../Rack/RubyProf.html">Rack::RubyProf</a>
111
+
112
+ </ul>
113
+ </nav>
114
+
115
+ </div>
116
+ </nav>
117
+
118
+ <div id="documentation" class="description">
119
+
120
+ <h1 id="label-Graph+Profiles">Graph Profiles</h1>
121
+
122
+ <p>Graph profiles show how long each method runs, which methods call it and
123
+ which methods it calls.</p>
124
+
125
+ <p>As an example, here is the output from running printers_test.rb:</p>
126
+
127
+ <p>Thread ID: 21277412</p>
128
+
129
+ <pre> %total %self total self children calls Name
130
+ --------------------------------------------------------------------------------
131
+ 100.00% 0.00% 8.77 0.00 8.77 1 #toplevel
132
+ 8.77 0.00 8.77 1/1 Object#run_primes
133
+ --------------------------------------------------------------------------------
134
+ 8.77 0.00 8.77 1/1 #toplevel
135
+ 100.00% 0.00% 8.77 0.00 8.77 1 Object#run_primes
136
+ 0.02 0.00 0.02 1/1 Object#make_random_array
137
+ 2.09 0.00 2.09 1/1 Object#find_largest
138
+ 6.66 0.00 6.66 1/1 Object#find_primes
139
+ --------------------------------------------------------------------------------
140
+ 6.63 4.06 2.56 500/501 Object#is_prime
141
+ 2.09 0.00 2.09 1/501 Object#find_largest
142
+ 99.48% 46.34% 8.72 4.06 4.66 501 Integer#upto
143
+ 0.00 0.00 0.00 61/61 Array#[]
144
+ 0.00 0.00 0.00 61/61 Fixnum#&gt;
145
+ 2.09 2.09 0.00 61/61 Kernel.sleep
146
+ 1.24 1.24 0.00 250862/250862 Fixnum#==
147
+ 1.33 1.33 0.00 250862/250862 Fixnum#%
148
+ --------------------------------------------------------------------------------
149
+ 6.66 0.01 6.64 1/1 Object#find_primes
150
+ 75.93% 0.17% 6.66 0.01 6.64 1 Array#select
151
+ 6.64 0.01 6.63 500/500 Object#is_prime
152
+ --------------------------------------------------------------------------------
153
+ 6.66 0.00 6.66 1/1 Object#run_primes
154
+ 75.93% 0.00% 6.66 0.00 6.66 1 Object#find_primes
155
+ 6.66 0.01 6.64 1/1 Array#select
156
+ --------------------------------------------------------------------------------
157
+ 6.64 0.01 6.63 500/500 Array#select
158
+ 75.76% 0.17% 6.64 0.01 6.63 500 Object#is_prime
159
+ 0.00 0.00 0.00 500/501 Fixnum#-
160
+ 6.63 4.06 2.56 500/501 Integer#upto
161
+ --------------------------------------------------------------------------------
162
+ 2.09 0.00 2.09 1/1 Object#run_primes
163
+ 23.89% 0.00% 2.09 0.00 2.09 1 Object#find_largest
164
+ 0.00 0.00 0.00 1/501 Fixnum#-
165
+ 2.09 0.00 2.09 1/501 Integer#upto
166
+ 0.00 0.00 0.00 1/1 Array#first
167
+ 0.00 0.00 0.00 1/1 Array#length
168
+ --------------------------------------------------------------------------------
169
+ 2.09 2.09 0.00 61/61 Integer#upto
170
+ 23.89% 23.89% 2.09 2.09 0.00 61 Kernel.sleep
171
+ --------------------------------------------------------------------------------
172
+ 1.33 1.33 0.00 250862/250862 Integer#upto
173
+ 15.12% 15.12% 1.33 1.33 0.00 250862 Fixnum#%
174
+ --------------------------------------------------------------------------------
175
+ 1.24 1.24 0.00 250862/250862 Integer#upto
176
+ 14.13% 14.13% 1.24 1.24 0.00 250862 Fixnum#==
177
+ --------------------------------------------------------------------------------
178
+ 0.02 0.00 0.02 1/1 Object#run_primes
179
+ 0.18% 0.00% 0.02 0.00 0.02 1 Object#make_random_array
180
+ 0.02 0.02 0.00 1/1 Array#each_index
181
+ 0.00 0.00 0.00 1/1 Class#new
182
+ --------------------------------------------------------------------------------
183
+ 0.02 0.02 0.00 1/1 Object#make_random_array
184
+ 0.18% 0.18% 0.02 0.02 0.00 1 Array#each_index
185
+ 0.00 0.00 0.00 500/500 Kernel.rand
186
+ 0.00 0.00 0.00 500/500 Array#[]=
187
+ --------------------------------------------------------------------------------
188
+ 0.00 0.00 0.00 500/501 Object#is_prime
189
+ 0.00 0.00 0.00 1/501 Object#find_largest
190
+ 0.00% 0.00% 0.00 0.00 0.00 501 Fixnum#-
191
+ --------------------------------------------------------------------------------
192
+ 0.00 0.00 0.00 1/1 Kernel.rand
193
+ 0.00% 0.00% 0.00 0.00 0.00 1 Integer#to_int
194
+ --------------------------------------------------------------------------------
195
+ 0.00 0.00 0.00 1/1 Object#find_largest
196
+ 0.00% 0.00% 0.00 0.00 0.00 1 Array#first
197
+ --------------------------------------------------------------------------------
198
+ 0.00 0.00 0.00 1/1 Class#new
199
+ 0.00% 0.00% 0.00 0.00 0.00 1 Array#initialize
200
+ --------------------------------------------------------------------------------
201
+ 0.00 0.00 0.00 1/1 Object#find_largest
202
+ 0.00% 0.00% 0.00 0.00 0.00 1 Array#length
203
+ --------------------------------------------------------------------------------
204
+ 0.00 0.00 0.00 1/1 Object#make_random_array
205
+ 0.00% 0.00% 0.00 0.00 0.00 1 Class#new
206
+ 0.00 0.00 0.00 1/1 Array#initialize
207
+ --------------------------------------------------------------------------------
208
+ 0.00 0.00 0.00 61/61 Integer#upto
209
+ 0.00% 0.00% 0.00 0.00 0.00 61 Fixnum#&gt;
210
+ --------------------------------------------------------------------------------
211
+ 0.00 0.00 0.00 61/61 Integer#upto
212
+ 0.00% 0.00% 0.00 0.00 0.00 61 Array#[]
213
+ --------------------------------------------------------------------------------
214
+ 0.00 0.00 0.00 500/500 Array#each_index
215
+ 0.00% 0.00% 0.00 0.00 0.00 500 Array#[]=
216
+ --------------------------------------------------------------------------------
217
+ 0.00 0.00 0.00 500/500 Array#each_index
218
+ 0.00% 0.00% 0.00 0.00 0.00 500 Kernel.rand
219
+ 0.00 0.00 0.00 1/1 Integer#to_int</pre>
220
+
221
+ <h2 id="label-Overview">Overview</h2>
222
+
223
+ <p>Dashed lines divide the report into entries, with one entry per method.
224
+ Entries are sorted by total time which is the time spent in the method
225
+ plus its children.</p>
226
+
227
+ <p>Each entry has a primary line demarked by values in the %total and %self
228
+ columns. The primary line represents the method being profiled. Lines
229
+ above it are the methods that called this method (parents) while the lines
230
+ below it are the methods it called (children).</p>
231
+
232
+ <p>All values are in seconds. For the primary line, the columns represent:</p>
233
+
234
+ <pre>%total - The percentage of time spent in this method and its children
235
+ %self - The percentage of time spent in this method
236
+ total - The time spent in this method and its children.
237
+ self - The time spent in this method.
238
+ children - The time spent in this method's children.
239
+ calls - The number of times this method was called.
240
+ name - The name of the method.</pre>
241
+
242
+ <p>The interpretation of method names is:</p>
243
+ <ul><li>
244
+ <p>toplevel - The root method that calls all other methods</p>
245
+ </li><li>
246
+ <p>MyObject#test - An instance method “test” of the class “MyObject”</p>
247
+ </li><li>
248
+ <p>&lt;Object:MyObject&gt;test - The &lt;&gt; characters indicate a singleton
249
+ method on a singleton class.</p>
250
+ </li></ul>
251
+
252
+ <p>For example, we see that 99.48% of the time was spent in Integer#upto and
253
+ its children. Of that time, 4.06 seconds was spent in Integer#upto itself
254
+ and 4.66 in its children. Overall, Integer#upto was called 501 times.</p>
255
+
256
+ <h2 id="label-Parents">Parents</h2>
257
+
258
+ <p>In each entry, the lines above the primary line are the methods that
259
+ called the current method. If the current method is a root method then no
260
+ parents are shown.</p>
261
+
262
+ <p>For parent lines, the columns represent:</p>
263
+
264
+ <pre>total - The time spent in the current method and it children on behalf of the parent method.
265
+ self - The time spent in this method on behalf of the parent method.
266
+ children - The time spent in this method's children on behalf of the parent.
267
+ calls - The number of times the parent method called this child</pre>
268
+
269
+ <p>Looking at Integer#upto again, we see that it was called 500 times from
270
+ Object#is_prime and 1 time from find_largest. Of the 8.72 total seconds
271
+ spent in Integer#upto, 6.63 were done for Object#is_prime and 2.09 for
272
+ Object#find_largest.</p>
273
+
274
+ <h2 id="label-Children">Children</h2>
275
+
276
+ <p>In each entry, the lines below the primary line are the methods that the
277
+ current method called. If the current method is a leaf method then no
278
+ children are shown.</p>
279
+
280
+ <p>For children lines, the columns represent:</p>
281
+
282
+ <pre>total - The time spent in the child, and its children, on behalf of the current method
283
+ self - The time spent in the child on behalf of the current method.
284
+ children - The time spent in the child's children (ie, granchildren) in behalf of the current method
285
+ calls - The number of times the child method was called by the current method.</pre>
286
+
287
+ <p>Taking our example of Integer#upto, we see that it called five other
288
+ methods - Array#[], Fixnum#&gt;, Kernel.sleep, Fixnum#= and Fixnum#%.
289
+ Looking at Kernel.sleep, we see that its spent 2.09 seconds working for
290
+ Integer#upto and its children spent 0 time working for Integer#upto. To
291
+ see the overall time Kernel.sleep took we would have to look up its entry
292
+ in the graph table.</p>
293
+
294
+ <p></p>
295
+
296
+ </div>
297
+
298
+
299
+
300
+ <footer id="validator-badges">
301
+ <p><a href="http://validator.w3.org/check/referer">[Validate]</a>
302
+ <p>Generated by <a href="https://github.com/rdoc/rdoc">RDoc</a> 3.12.
303
+ <p>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish Rdoc Generator</a> 3.
304
+ </footer>
305
+
data/doc/images/add.png ADDED
Binary file
data/doc/images/brick.png ADDED
Binary file
data/doc/images/brick_link.png ADDED
Binary file
data/doc/images/bug.png ADDED
Binary file
data/doc/images/bullet_black.png ADDED
Binary file
data/doc/images/bullet_toggle_minus.png ADDED
Binary file
data/doc/images/bullet_toggle_plus.png ADDED
Binary file
data/doc/images/date.png ADDED
Binary file
data/doc/images/delete.png ADDED
Binary file
data/doc/images/find.png ADDED
Binary file
data/doc/images/loadingAnimation.gif ADDED
Binary file
data/doc/images/macFFBgHack.png ADDED
Binary file
data/doc/images/package.png ADDED
Binary file
data/doc/images/page_green.png ADDED
Binary file
data/doc/images/page_white_text.png ADDED
Binary file
data/doc/images/page_white_width.png ADDED
Binary file
data/doc/images/plugin.png ADDED
Binary file
data/doc/images/ruby.png ADDED
Binary file
data/doc/images/tag_blue.png ADDED
Binary file
data/doc/images/tag_green.png ADDED
Binary file
data/doc/images/transparent.png ADDED
Binary file
data/doc/images/wrench.png ADDED
Binary file
data/doc/images/wrench_orange.png ADDED
Binary file
data/doc/images/zoom.png ADDED
Binary file
data/doc/index.html ADDED
@@ -0,0 +1,639 @@
1
+ <!DOCTYPE html>
2
+
3
+ <html>
4
+ <head>
5
+ <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
6
+
7
+ <title>ruby-prof</title>
8
+
9
+ <link type="text/css" media="screen" href="./rdoc.css" rel="stylesheet">
10
+
11
+ <script type="text/javascript">
12
+ var rdoc_rel_prefix = "./";
13
+ </script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="./js/jquery.js"></script>
16
+ <script type="text/javascript" charset="utf-8" src="./js/navigation.js"></script>
17
+ <script type="text/javascript" charset="utf-8" src="./js/search_index.js"></script>
18
+ <script type="text/javascript" charset="utf-8" src="./js/search.js"></script>
19
+ <script type="text/javascript" charset="utf-8" src="./js/searcher.js"></script>
20
+ <script type="text/javascript" charset="utf-8" src="./js/darkfish.js"></script>
21
+
22
+
23
+ <body>
24
+ <nav id="metadata">
25
+ <nav id="home-section" class="section">
26
+ <h3 class="section-header">
27
+ <a href="./index.html">Home</a>
28
+ <a href="./table_of_contents.html#classes">Classes</a>
29
+ <a href="./table_of_contents.html#methods">Methods</a>
30
+ </h3>
31
+ </nav>
32
+
33
+
34
+ <nav id="search-section" class="section project-section" class="initially-hidden">
35
+ <form action="#" method="get" accept-charset="utf-8">
36
+ <h3 class="section-header">
37
+ <input type="text" name="search" placeholder="Search" id="search-field"
38
+ title="Type to search, Up and Down to navigate, Enter to load">
39
+ </h3>
40
+ </form>
41
+
42
+ <ul id="search-results" class="initially-hidden"></ul>
43
+ </nav>
44
+
45
+
46
+ <div id="project-metadata">
47
+ <nav id="fileindex-section" class="section project-section">
48
+ <h3 class="section-header">Pages</h3>
49
+
50
+ <ul>
51
+
52
+ <li class="file"><a href="./LICENSE.html">LICENSE</a>
53
+
54
+ <li class="file"><a href="./README_rdoc.html">README</a>
55
+
56
+ <li class="file"><a href="./examples/flat_txt.html">flat</a>
57
+
58
+ <li class="file"><a href="./examples/graph_txt.html">graph</a>
59
+
60
+ </ul>
61
+ </nav>
62
+
63
+ <nav id="classindex-section" class="section project-section">
64
+ <h3 class="section-header">Class and Module Index</h3>
65
+
66
+ <ul class="link-list">
67
+
68
+ <li><a href="./RubyProf.html">RubyProf</a>
69
+
70
+ <li><a href="./RubyProf/AbstractPrinter.html">RubyProf::AbstractPrinter</a>
71
+
72
+ <li><a href="./RubyProf/AggregateCallInfo.html">RubyProf::AggregateCallInfo</a>
73
+
74
+ <li><a href="./RubyProf/CallInfo.html">RubyProf::CallInfo</a>
75
+
76
+ <li><a href="./RubyProf/CallInfoPrinter.html">RubyProf::CallInfoPrinter</a>
77
+
78
+ <li><a href="./RubyProf/CallInfoVisitor.html">RubyProf::CallInfoVisitor</a>
79
+
80
+ <li><a href="./RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>
81
+
82
+ <li><a href="./RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>
83
+
84
+ <li><a href="./RubyProf/Cmd.html">RubyProf::Cmd</a>
85
+
86
+ <li><a href="./RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>
87
+
88
+ <li><a href="./RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>
89
+
90
+ <li><a href="./RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
91
+
92
+ <li><a href="./RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
93
+
94
+ <li><a href="./RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
95
+
96
+ <li><a href="./RubyProf/MethodInfo.html">RubyProf::MethodInfo</a>
97
+
98
+ <li><a href="./RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>
99
+
100
+ <li><a href="./RubyProf/Profile.html">RubyProf::Profile</a>
101
+
102
+ <li><a href="./RubyProf/ProfileTask.html">RubyProf::ProfileTask</a>
103
+
104
+ <li><a href="./RubyProf/Test.html">RubyProf::Test</a>
105
+
106
+ <li><a href="./RubyProf/Thread.html">RubyProf::Thread</a>
107
+
108
+ <li><a href="./Rack.html">Rack</a>
109
+
110
+ <li><a href="./Rack/RubyProf.html">Rack::RubyProf</a>
111
+
112
+ </ul>
113
+ </nav>
114
+
115
+ </div>
116
+ </nav>
117
+
118
+ <div id="documentation" class="description">
119
+
120
+ <h1 id="label-ruby-prof">ruby-prof</h1>
121
+
122
+ <h2 id="label-Overview">Overview</h2>
123
+
124
+ <p>ruby-prof is a fast code profiler for Ruby. Its features include:</p>
125
+ <ul><li>
126
+ <p>Speed - it is a C extension and therefore many times faster than the
127
+ standard Ruby profiler.</p>
128
+ </li><li>
129
+ <p>Modes - Ruby prof can measure a number of different parameters, including
130
+ call times, memory usage and object allocations.</p>
131
+ </li><li>
132
+ <p>Reports - can generate text and cross-referenced html reports</p>
133
+ <ul><li>
134
+ <p>Flat Profiles - similar to the reports generated by the standard Ruby
135
+ profiler</p>
136
+ </li><li>
137
+ <p>Graph profiles - similar to GProf, these show how long a method runs, which
138
+ methods call it and which methods it calls.</p>
139
+ </li><li>
140
+ <p>Call tree profiles - outputs results in the calltree format suitable for
141
+ the KCacheGrind profiling tool.</p>
142
+ </li><li>
143
+ <p>Many more – see reports section of this <a
144
+ href="README_rdoc.html">README</a>.</p>
145
+ </li></ul>
146
+ </li><li>
147
+ <p>Threads - supports profiling multiple threads simultaneously</p>
148
+ </li></ul>
149
+
150
+ <h2 id="label-Requirements">Requirements</h2>
151
+
152
+ <p>ruby-prof requires Ruby 1.8.7 or 1.9.2 and higher.</p>
153
+
154
+ <p>If you are running Linux or Unix you’ll need a C compiler so the extension
155
+ can be compiled when it is installed.</p>
156
+
157
+ <p>If you are running Windows, then you may need to install the Windows
158
+ specific RubyGem which includes an already built extension (see Install
159
+ section).</p>
160
+
161
+ <h2 id="label-Install">Install</h2>
162
+
163
+ <p>The easiest way to install ruby-prof is by using Ruby Gems. To install:</p>
164
+
165
+ <pre>gem install ruby-prof</pre>
166
+
167
+ <p>If you’re on windows then a prebuilt binary gem is available. You may of
168
+ course compile it yourself via use of devkit on MinGW.</p>
169
+
170
+ <h2 id="label-Usage">Usage</h2>
171
+
172
+ <p>There are two ways of running ruby-prof, via the command line or via its
173
+ API.</p>
174
+
175
+ <h3 id="label-ruby-prof+executable">ruby-prof executable</h3>
176
+
177
+ <p>The first is to use ruby-prof to run the Ruby program you want to profile.
178
+ For more information refer to the documentation of the ruby-prof command.</p>
179
+
180
+ <h3 id="label-ruby-prof+API">ruby-prof API</h3>
181
+
182
+ <p>The second way is to use the ruby-prof API to profile particular segments
183
+ of code.</p>
184
+
185
+ <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
186
+
187
+ <span class="ruby-comment"># Profile the code</span>
188
+ <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
189
+ <span class="ruby-operator">...</span>
190
+ [<span class="ruby-identifier">code</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">profile</span>]
191
+ <span class="ruby-operator">...</span>
192
+ <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
193
+
194
+ <span class="ruby-comment"># Print a flat profile to text</span>
195
+ <span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">FlatPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
196
+ <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>)
197
+ </pre>
198
+
199
+ <p>Alternatively, you can use a block to tell ruby-prof what to profile:</p>
200
+
201
+ <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
202
+
203
+ <span class="ruby-comment"># Profile the code</span>
204
+ <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
205
+ <span class="ruby-operator">...</span>
206
+ [<span class="ruby-identifier">code</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">profile</span>]
207
+ <span class="ruby-operator">...</span>
208
+ <span class="ruby-keyword">end</span>
209
+
210
+ <span class="ruby-comment"># Print a graph profile to text</span>
211
+ <span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GraphPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
212
+ <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>, {})
213
+ </pre>
214
+
215
+ <p>ruby-prof also supports pausing and resuming profiling runs.</p>
216
+
217
+ <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
218
+
219
+ <span class="ruby-comment"># Profile the code</span>
220
+ <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
221
+ [<span class="ruby-identifier">code</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">profile</span>]
222
+ <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">pause</span>
223
+ [<span class="ruby-identifier">other</span> <span class="ruby-identifier">code</span>]
224
+ <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span>
225
+ [<span class="ruby-identifier">code</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">profile</span>]
226
+ <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
227
+ </pre>
228
+
229
+ <p>Note that resume will automatically call start if a profiling run has not
230
+ yet started. In addition, resume can also take a block:</p>
231
+
232
+ <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
233
+
234
+ <span class="ruby-comment"># Profile the code</span>
235
+ <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span> <span class="ruby-keyword">do</span>
236
+ [<span class="ruby-identifier">code</span> <span class="ruby-identifier">to</span> <span class="ruby-identifier">profile</span>]
237
+ <span class="ruby-keyword">end</span>
238
+
239
+ <span class="ruby-identifier">data</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
240
+ </pre>
241
+
242
+ <p>With this usage, resume will automatically call pause at the end of the
243
+ block.</p>
244
+
245
+ <h2 id="label-Method+and+Thread+Elimination">Method and Thread Elimination</h2>
246
+
247
+ <p>ruby-prof supports eliminating specific methods and threads from profiling
248
+ results. This is useful for reducing connectivity in the call graph, making
249
+ it easier to identify the source of performance problems when using a graph
250
+ printer.</p>
251
+
252
+ <p>For example, consider Integer#times: it’s hardly ever useful to know how
253
+ much time is spent in the method itself. We’re much more interested in how
254
+ much the passed in block contributes to the time spent in the method which
255
+ contains the Integer#times call.</p>
256
+
257
+ <p>Methods are eliminated from the collected data by calling
258
+ `eliminate_methods!` on the profiling result, before submitting it to a
259
+ printer.</p>
260
+
261
+ <pre>result = RubyProf.stop
262
+ result.eliminate_methods!([/Integer#times/])</pre>
263
+
264
+ <p>The argument given to `eliminate_methods!` is either an array of regular
265
+ expressions, or the name of a file containing a list of regular expressions
266
+ (line separated text).</p>
267
+
268
+ <p>After eliminating methods the resulting profile will appear exactly as if
269
+ those methods had been inlined at their call sites.</p>
270
+
271
+ <p>In a similar manner, threads can be excluded so they are not profiled at
272
+ all. To do this, pass an array of threads to exclude to ruby-prof:</p>
273
+
274
+ <pre>RubyProf::exclude_threads = [ thread2 ]
275
+ RubyProf.start</pre>
276
+
277
+ <p>Note that the excluded threads must be specified <strong>before</strong>
278
+ profiling.</p>
279
+
280
+ <h2 id="label-Benchmarking+full+load+time+including+rubygems+startup+cost+%3D%3D">Benchmarking full load time including rubygems startup cost ==</h2>
281
+
282
+ <p>If you want to get a more accurate measurement of what takes all of a gem’s
283
+ bin/xxx command to load, you may want to also measure rubygems’ startup
284
+ penalty. You can do this by calling into bin/ruby-prof directly, ex:</p>
285
+
286
+ <p>$ gem which ruby-prof</p>
287
+
288
+ <pre>g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/lib/ruby-prof.rb</pre>
289
+
290
+ <p>now run it thus (substitute lib/ruby-prof.rb with bin/ruby-prof):</p>
291
+
292
+ <p>$ ruby g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/bin/ruby-prof
293
+ g:192binsome_installed_gem_command</p>
294
+
295
+ <p>or</p>
296
+
297
+ <p>$ ruby g:/192/lib/ruby/gems/1.9.1/gems/ruby-prof-0.10.2/bin/ruby-prof
298
+ ./some_file_that_does_a_require_rubygems_at_the_beginning.rb</p>
299
+
300
+ <h2 id="label-Profiling+Tests">Profiling Tests</h2>
301
+
302
+ <p>ruby-prof supports profiling tests cases written using Ruby’s built-in unit
303
+ test framework (ie, test derived from Test::Unit::TestCase). To enable
304
+ profiling simply add the following line of code to within your test class:</p>
305
+
306
+ <pre>include RubyProf::Test</pre>
307
+
308
+ <p>Each test method is profiled separately. ruby-prof will run each test
309
+ method once as a warmup and then ten additional times to gather profile
310
+ data. Note that the profile data will <strong>not</strong> include the
311
+ class’s setup or teardown methods.</p>
312
+
313
+ <p>Separate reports are generated for each method and saved, by default, in
314
+ the test process’s working directory. To change this, or other profiling
315
+ options, modify your test class’s PROFILE_OPTIONS hash table. To globally
316
+ change test profiling options, modify RubyProf::Test::PROFILE_OPTIONS.</p>
317
+
318
+ <h2 id="label-Profiling+Rails">Profiling Rails</h2>
319
+
320
+ <p>To profile a Rails application it is vital to run it using production like
321
+ settings (cache classes, cache view lookups, etc.). Otherwise, Rail’s
322
+ dependency loading code will overwhelm any time spent in the application
323
+ itself (our tests show that Rails dependency loading causes a roughly 6x
324
+ slowdown). The best way to do this is create a new Rails environment,
325
+ profile.rb.</p>
326
+
327
+ <p>So to profile Rails:</p>
328
+ <ol><li>
329
+ <p>Create a new profile.rb environment. Make sure to turn on cache_classes
330
+ and cache_template_loading. Otherwise your profiling results will be
331
+ overwhelemed by the time Rails spends loading required files. You should
332
+ likely turn off caching.</p>
333
+ </li><li>
334
+ <p>Add the ruby-prof to your gemfile:</p>
335
+
336
+ <pre>group :profile do
337
+ gem 'ruby-prof'
338
+ end</pre>
339
+ </li><li>
340
+ <p>Add the ruby prof rack adapter to your middleware stack. One way to do
341
+ this is by adding the following code to config.ru:</p>
342
+
343
+ <pre class="ruby"><span class="ruby-keyword">if</span> <span class="ruby-constant">Rails</span>.<span class="ruby-identifier">env</span>.<span class="ruby-identifier">profile?</span>
344
+ <span class="ruby-identifier">use</span> <span class="ruby-constant">Rack</span><span class="ruby-operator">::</span><span class="ruby-constant">RubyProf</span>, :<span class="ruby-identifier">path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">'/temp/profile'</span>
345
+ <span class="ruby-keyword">end</span>
346
+ </pre>
347
+
348
+ <p>The path is where you want profiling results to be stored. By default the
349
+ rack adapter will generate a html call graph report and flat text report.</p>
350
+ </li><li>
351
+ <p>Now make a request to your running server. New profiling information will
352
+ be generated for each request. Note that each request will overwrite the
353
+ profiling reports created by the previous request!</p>
354
+ </li></ol>
355
+
356
+ <h2 id="label-Reports">Reports</h2>
357
+
358
+ <p>ruby-prof can generate a number of different reports:</p>
359
+ <ul><li>
360
+ <p>Flat Reports</p>
361
+ </li><li>
362
+ <p>Graph Reports</p>
363
+ </li><li>
364
+ <p>HTML Graph Reports</p>
365
+ </li><li>
366
+ <p>Call graphs</p>
367
+ </li><li>
368
+ <p>Call stack reports</p>
369
+ </li><li>
370
+ <p>More!</p>
371
+ </li></ul>
372
+
373
+ <p>Flat profiles show the overall time spent in each method. They are a good
374
+ of quickly identifying which methods take the most time. An example of a
375
+ flat profile and an explanation can be found in <a
376
+ href="http://github.com/rdp/ruby-prof/tree/master/examples/flat.txt">examples/flat.txt</a>.</p>
377
+
378
+ <p>There are several varieties of these – run $ ruby-prof –help</p>
379
+
380
+ <p>Graph profiles also show the overall time spent in each method. In
381
+ addition, they also show which methods call the current method and which
382
+ methods its calls. Thus they are good for understanding how methods gets
383
+ called and provide insight into the flow of your program. An example text
384
+ graph profile is located at <a
385
+ href="http://github.com/rdp/ruby-prof/tree/master/examples/graph.txt">examples/graph.txt</a>.</p>
386
+
387
+ <p>HTML Graph profiles are the same as graph profiles, except output is
388
+ generated in hyper-linked HTML. Since graph profiles can be quite large,
389
+ the embedded links make it much easier to navigate the results. An example
390
+ html graph profile is located at <a
391
+ href="http://github.com/rdp/ruby-prof/tree/master/examples/graph.html">examples/graph.html</a>.</p>
392
+
393
+ <p>Call graphs output results in the calltree profile format which is used by
394
+ KCachegrind. Call graph support was generously donated by Carl Shimer. More
395
+ information about the format can be found at the <a
396
+ href="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat">KCachegrind</a>
397
+ site.</p>
398
+
399
+ <p>Call stack reports produce a HTML visualization of the time spent in each
400
+ execution path of the profiled code. An example can be found at <a
401
+ href="http://github.com/rdp/ruby-prof/tree/master/examples/call_stack.html">examples/stack.html</a>.</p>
402
+
403
+ <p>Another good example: [<a
404
+ href="http://twitpic.com/28z94a">twitpic.com/28z94a</a>]</p>
405
+
406
+ <p>Finally, there’s a so called MultiPrinter which can generate several
407
+ reports in one profiling run. See <a
408
+ href="http://github.com/rdp/ruby-prof/tree/master/examples/multi.stack.html">examples/multi.stack.html</a>.</p>
409
+
410
+ <p>There is also a graphviz .dot visualiser.</p>
411
+
412
+ <h2 id="label-Printers">Printers</h2>
413
+
414
+ <p>Reports are created by printers. Supported printers include:</p>
415
+ <ul><li>
416
+ <p><a href="RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a> - Creates a
417
+ flat report in text format</p>
418
+ </li><li>
419
+ <p><a
420
+ href="RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
421
+ - same as above but more verbose</p>
422
+ </li><li>
423
+ <p><a href="RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a> - Creates a
424
+ call graph report in text format</p>
425
+ </li><li>
426
+ <p><a href="RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a> -
427
+ Creates a call graph report in HTML (separate files per thread)</p>
428
+ </li><li>
429
+ <p><a href="RubyProf/DotPrinter.html">RubyProf::DotPrinter</a> - Creates a
430
+ call graph report in GraphViz's DOT format which can be converted to an
431
+ image</p>
432
+ </li><li>
433
+ <p><a href="RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a> -
434
+ Creates a call tree report compatible with KCachegrind.</p>
435
+ </li><li>
436
+ <p><a href="RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a> -
437
+ Creates a HTML visualization of the Ruby stack</p>
438
+ </li><li>
439
+ <p><a href="RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a> - Uses the
440
+ other printers to create several reports in one profiling run</p>
441
+ </li><li>
442
+ <p>More!</p>
443
+ </li></ul>
444
+
445
+ <p>To use a printer:</p>
446
+
447
+ <pre class="ruby"><span class="ruby-operator">...</span>
448
+ <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">end</span>
449
+ <span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GraphPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
450
+ <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>, :<span class="ruby-identifier">min_percent</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value">2</span>)
451
+ </pre>
452
+
453
+ <p>The first parameter is any writable IO object such as STDOUT or a file. The
454
+ second parameter, specifies the minimum percentage a method must take to be
455
+ printed. Percentages should be specified as integers in the range 0 to
456
+ 100. For more information please see the documentation for the different
457
+ printers.</p>
458
+
459
+ <p>The other option is :print_file =&gt; true (default false), which adds the
460
+ filename to the output (GraphPrinter only).</p>
461
+
462
+ <p>The MultiPrinter differs from the other printers in that it requires a
463
+ directory path and a basename for the files it produces.</p>
464
+
465
+ <pre class="ruby"><span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">MultiPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
466
+ <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(:<span class="ruby-identifier">path</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;.&quot;</span>, :<span class="ruby-identifier">profile</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;profile&quot;</span>)
467
+ </pre>
468
+
469
+ <h2 id="label-Measurements">Measurements</h2>
470
+
471
+ <p>Depending on the mode and platform, ruby-prof can measure various aspects
472
+ of a Ruby program. Supported measurements include:</p>
473
+ <ul><li>
474
+ <p>process time (RubyProf::PROCESS_TIME)</p>
475
+ </li><li>
476
+ <p>wall time (RubyProf::WALL_TIME)</p>
477
+ </li><li>
478
+ <p>cpu time (RubyProf::CPU_TIME)</p>
479
+ </li><li>
480
+ <p>object allocations (RubyProf::ALLOCATIONS)</p>
481
+ </li><li>
482
+ <p>memory usage (RubyProf::MEMORY)</p>
483
+ </li><li>
484
+ <p>garbage collections runs (RubyProf::GC_RUNS)</p>
485
+ </li><li>
486
+ <p>garbage collection time (RubyProf::GC_TIME)</p>
487
+ </li></ul>
488
+
489
+ <p>Process time measures the time used by a process between any two moments.
490
+ It is unaffected by other processes concurrently running on the system.
491
+ Note that Windows does not support measuring process times - therefore,
492
+ measurements on Windows defaults to wall time.</p>
493
+
494
+ <p>Wall time measures the real-world time elapsed between any two moments. If
495
+ there are other processes concurrently running on the system that use
496
+ significant CPU or disk time during a profiling run then the reported
497
+ results will be too large.</p>
498
+
499
+ <p>CPU time uses the CPU clock counter to measure time. The returned values
500
+ are dependent on the correctly setting the CPU’s frequency. This mode is
501
+ only supported on Pentium or PowerPC platforms (linux only).</p>
502
+
503
+ <p>Object allocation reports show how many objects each method in a program
504
+ allocates. This support was added by Sylvain Joyeux and requires a patched
505
+ Ruby interpreter. For more information and the patch, please see: <a
506
+ href="http://rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700">rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700</a></p>
507
+
508
+ <p>Memory usage reports show how much memory each method in a program uses.
509
+ This support was added by Alexander Dymo and requires a patched Ruby
510
+ interpreter. For more information, see: <a
511
+ href="http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062">rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062</a></p>
512
+
513
+ <p>Garbage collection runs report how many times Ruby’s garbage collector is
514
+ invoked during a profiling session. This support was added by Jeremy
515
+ Kemper and requires a patched Ruby interpreter. For more information, see:
516
+ <a
517
+ href="http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062">rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062</a></p>
518
+
519
+ <p>Garbage collection time reports how much time is spent in Ruby’s garbage
520
+ collector during a profiling session. This support was added by Jeremy
521
+ Kemper and requires a patched Ruby interpreter. For more information, see:
522
+ <a
523
+ href="http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062">rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062</a></p>
524
+
525
+ <p>To set the measurement:</p>
526
+ <ul><li>
527
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
528
+ RubyProf::PROCESS_TIME</p>
529
+ </li><li>
530
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
531
+ RubyProf::WALL_TIME</p>
532
+ </li><li>
533
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
534
+ RubyProf::CPU_TIME</p>
535
+ </li><li>
536
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
537
+ RubyProf::ALLOCATIONS</p>
538
+ </li><li>
539
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
540
+ RubyProf::MEMORY</p>
541
+ </li><li>
542
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
543
+ RubyProf::GC_RUNS</p>
544
+ </li><li>
545
+ <p><a href="RubyProf.html#method-c-measure_mode">RubyProf.measure_mode</a> =
546
+ RubyProf::GC_TIME</p>
547
+ </li></ul>
548
+
549
+ <p>The default value is RubyProf::PROCESS_TIME.</p>
550
+
551
+ <p>You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
552
+ environment variable:</p>
553
+ <ul><li>
554
+ <p>export RUBY_PROF_MEASURE_MODE=process</p>
555
+ </li><li>
556
+ <p>export RUBY_PROF_MEASURE_MODE=wall</p>
557
+ </li><li>
558
+ <p>export RUBY_PROF_MEASURE_MODE=cpu</p>
559
+ </li><li>
560
+ <p>export RUBY_PROF_MEASURE_MODE=allocations</p>
561
+ </li><li>
562
+ <p>export RUBY_PROF_MEASURE_MODE=memory</p>
563
+ </li><li>
564
+ <p>export RUBY_PROF_MEASURE_MODE=gc_runs</p>
565
+ </li><li>
566
+ <p>export RUBY_PROF_MEASURE_MODE=gc_time</p>
567
+ </li></ul>
568
+
569
+ <p>On Linux, process time is measured using the clock method provided by the C
570
+ runtime library. Note that the clock method does not report time spent in
571
+ the kernel or child processes and therefore does not measure time spent in
572
+ methods such as Kernel.sleep method. If you need to measure these values,
573
+ then use wall time. Wall time is measured using the gettimeofday kernel
574
+ method.</p>
575
+
576
+ <p>On Windows, timings default to wall times. If you set the clock mode to
577
+ PROCESS_TIME, then timing are read using the clock method provided by the C
578
+ runtime library. Note though, these values are wall times on Windows and
579
+ not process times like on Linux. Wall time is measured using the
580
+ GetLocalTime API.</p>
581
+
582
+ <p>If you use wall time, the results will be affected by other processes
583
+ running on your computer, network delays, disk access, etc. As result, for
584
+ the best results, try to make sure your computer is only performing your
585
+ profiling run and is otherwise quiescent.</p>
586
+
587
+ <p>On both platforms, cpu time is measured using the RDTSC assembly function
588
+ provided by the Pentium and PowerPC platforms. CPU time is dependent on the
589
+ cpu’s frequency. On Linux, ruby-prof attempts to read this value from
590
+ “/proc/cpuinfo.” On Windows, you must manually specify the clock
591
+ frequency. This can be done using the RUBY_PROF_CPU_FREQUENCY environment
592
+ variable:</p>
593
+
594
+ <pre>export RUBY_PROF_CPU_FREQUENCY=&lt;value&gt;</pre>
595
+
596
+ <p>You can also directly set the cpu frequency by calling:</p>
597
+
598
+ <pre>RubyProf.cpu_frequency = &lt;value&gt;</pre>
599
+
600
+ <h2 id="label-Multi-threaded+Applications">Multi-threaded Applications</h2>
601
+
602
+ <p>Unfortunately, Ruby does not provide an internal api for detecting thread
603
+ context switches in 1.8. As a result, the timings ruby-prof reports for
604
+ each thread may be slightly inaccurate. In particular, this will happen
605
+ for newly spawned threads that go to sleep immediately (their first call).
606
+ For instance, if you use Ruby’s timeout library to wait for 2 seconds, the
607
+ 2 seconds will be assigned to the foreground thread and not the newly
608
+ created background thread. These errors can largely be avoided if the
609
+ background thread performs any operation before going to sleep.</p>
610
+
611
+ <h2 id="label-Performance">Performance</h2>
612
+
613
+ <p>Significant effort has been put into reducing ruby-prof’s overhead as much
614
+ as possible. Our tests show that the overhead associated with profiling
615
+ code varies considerably with the code being profiled. Most programs will
616
+ run approximately twice as slow while highly recursive programs (like the
617
+ fibonacci series test) will run three times slower.</p>
618
+
619
+ <h2 id="label-License">License</h2>
620
+
621
+ <p>See <a href="LICENSE.html">LICENSE</a> for license information.</p>
622
+
623
+ <h2 id="label-Development">Development</h2>
624
+
625
+ <p>Code is located at <a
626
+ href="http://github.com/rdp/ruby-prof">github.com/rdp/ruby-prof</a></p>
627
+
628
+ <p>Google group/mailing list: <a
629
+ href="http://groups.google.com/group/ruby-optimization">groups.google.com/group/ruby-optimization</a></p>
630
+
631
+ </div>
632
+
633
+
634
+ <footer id="validator-badges">
635
+ <p><a href="http://validator.w3.org/check/referer">[Validate]</a>
636
+ <p>Generated by <a href="https://github.com/rdoc/rdoc">RDoc</a> 3.12.
637
+ <p>Generated with the <a href="http://deveiate.org/projects/Darkfish-Rdoc/">Darkfish Rdoc Generator</a> 3.
638
+ </footer>
639
+