ruby-prof 0.17.0 → 0.18.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (185) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGES +500 -482
  3. data/LICENSE +24 -24
  4. data/README.rdoc +487 -485
  5. data/Rakefile +113 -113
  6. data/bin/ruby-prof +345 -345
  7. data/bin/ruby-prof-check-trace +45 -45
  8. data/examples/flat.txt +50 -50
  9. data/examples/graph.dot +84 -84
  10. data/examples/graph.html +823 -823
  11. data/examples/graph.txt +139 -139
  12. data/examples/multi.flat.txt +23 -23
  13. data/examples/multi.graph.html +760 -760
  14. data/examples/multi.grind.dat +114 -114
  15. data/examples/multi.stack.html +547 -547
  16. data/examples/stack.html +547 -547
  17. data/ext/ruby_prof/extconf.rb +68 -68
  18. data/ext/ruby_prof/rp_call_info.c +425 -425
  19. data/ext/ruby_prof/rp_call_info.h +53 -53
  20. data/ext/ruby_prof/rp_measure.c +40 -40
  21. data/ext/ruby_prof/rp_measure.h +45 -45
  22. data/ext/ruby_prof/rp_measure_allocations.c +76 -76
  23. data/ext/ruby_prof/rp_measure_cpu_time.c +136 -136
  24. data/ext/ruby_prof/rp_measure_gc_runs.c +73 -73
  25. data/ext/ruby_prof/rp_measure_gc_time.c +60 -60
  26. data/ext/ruby_prof/rp_measure_memory.c +77 -77
  27. data/ext/ruby_prof/rp_measure_process_time.c +71 -71
  28. data/ext/ruby_prof/rp_measure_wall_time.c +45 -45
  29. data/ext/ruby_prof/rp_method.c +630 -636
  30. data/ext/ruby_prof/rp_method.h +75 -75
  31. data/ext/ruby_prof/rp_stack.c +173 -173
  32. data/ext/ruby_prof/rp_stack.h +63 -63
  33. data/ext/ruby_prof/rp_thread.c +277 -276
  34. data/ext/ruby_prof/rp_thread.h +27 -27
  35. data/ext/ruby_prof/ruby_prof.c +794 -774
  36. data/ext/ruby_prof/ruby_prof.h +60 -59
  37. data/ext/ruby_prof/vc/ruby_prof.sln +20 -21
  38. data/ext/ruby_prof/vc/{ruby_prof_20.vcxproj → ruby_prof.vcxproj} +31 -0
  39. data/lib/ruby-prof.rb +68 -68
  40. data/lib/ruby-prof/aggregate_call_info.rb +76 -76
  41. data/lib/ruby-prof/assets/call_stack_printer.css.html +116 -116
  42. data/lib/ruby-prof/assets/call_stack_printer.js.html +384 -384
  43. data/lib/ruby-prof/call_info.rb +115 -115
  44. data/lib/ruby-prof/call_info_visitor.rb +40 -40
  45. data/lib/ruby-prof/compatibility.rb +179 -178
  46. data/lib/ruby-prof/method_info.rb +121 -121
  47. data/lib/ruby-prof/printers/abstract_printer.rb +104 -103
  48. data/lib/ruby-prof/printers/call_info_printer.rb +41 -41
  49. data/lib/ruby-prof/printers/call_stack_printer.rb +265 -265
  50. data/lib/ruby-prof/printers/call_tree_printer.rb +143 -143
  51. data/lib/ruby-prof/printers/dot_printer.rb +132 -132
  52. data/lib/ruby-prof/printers/flat_printer.rb +70 -70
  53. data/lib/ruby-prof/printers/flat_printer_with_line_numbers.rb +83 -83
  54. data/lib/ruby-prof/printers/graph_html_printer.rb +249 -249
  55. data/lib/ruby-prof/printers/graph_printer.rb +116 -116
  56. data/lib/ruby-prof/printers/multi_printer.rb +84 -84
  57. data/lib/ruby-prof/profile.rb +26 -26
  58. data/lib/ruby-prof/profile/exclude_common_methods.rb +207 -201
  59. data/lib/ruby-prof/profile/legacy_method_elimination.rb +50 -49
  60. data/lib/ruby-prof/rack.rb +174 -174
  61. data/lib/ruby-prof/task.rb +147 -147
  62. data/lib/ruby-prof/thread.rb +35 -35
  63. data/lib/ruby-prof/version.rb +3 -3
  64. data/lib/unprof.rb +10 -10
  65. data/ruby-prof.gemspec +58 -58
  66. data/test/abstract_printer_test.rb +53 -0
  67. data/test/aggregate_test.rb +136 -136
  68. data/test/basic_test.rb +128 -128
  69. data/test/block_test.rb +74 -74
  70. data/test/call_info_test.rb +78 -78
  71. data/test/call_info_visitor_test.rb +31 -31
  72. data/test/duplicate_names_test.rb +32 -32
  73. data/test/dynamic_method_test.rb +55 -55
  74. data/test/enumerable_test.rb +21 -21
  75. data/test/exceptions_test.rb +24 -16
  76. data/test/exclude_methods_test.rb +146 -146
  77. data/test/exclude_threads_test.rb +53 -53
  78. data/test/fiber_test.rb +79 -79
  79. data/test/issue137_test.rb +63 -63
  80. data/test/line_number_test.rb +80 -80
  81. data/test/measure_allocations_test.rb +26 -26
  82. data/test/measure_cpu_time_test.rb +212 -213
  83. data/test/measure_gc_runs_test.rb +32 -32
  84. data/test/measure_gc_time_test.rb +36 -36
  85. data/test/measure_memory_test.rb +33 -33
  86. data/test/measure_process_time_test.rb +61 -63
  87. data/test/measure_wall_time_test.rb +255 -255
  88. data/test/method_elimination_test.rb +84 -84
  89. data/test/module_test.rb +45 -45
  90. data/test/multi_printer_test.rb +104 -104
  91. data/test/no_method_class_test.rb +15 -15
  92. data/test/pause_resume_test.rb +166 -166
  93. data/test/prime.rb +54 -54
  94. data/test/printers_test.rb +275 -275
  95. data/test/printing_recursive_graph_test.rb +127 -127
  96. data/test/rack_test.rb +157 -157
  97. data/test/recursive_test.rb +215 -215
  98. data/test/singleton_test.rb +38 -38
  99. data/test/stack_printer_test.rb +77 -78
  100. data/test/stack_test.rb +138 -138
  101. data/test/start_stop_test.rb +112 -112
  102. data/test/test_helper.rb +267 -275
  103. data/test/thread_test.rb +187 -187
  104. data/test/unique_call_path_test.rb +202 -202
  105. data/test/yarv_test.rb +55 -55
  106. metadata +17 -96
  107. data/doc/LICENSE.html +0 -115
  108. data/doc/README_rdoc.html +0 -637
  109. data/doc/Rack.html +0 -96
  110. data/doc/Rack/RubyProf.html +0 -233
  111. data/doc/Rack/RubyProf/RackProfiler.html +0 -343
  112. data/doc/RubyProf.html +0 -974
  113. data/doc/RubyProf/AbstractPrinter.html +0 -625
  114. data/doc/RubyProf/AggregateCallInfo.html +0 -552
  115. data/doc/RubyProf/CallInfo.html +0 -579
  116. data/doc/RubyProf/CallInfoPrinter.html +0 -121
  117. data/doc/RubyProf/CallInfoVisitor.html +0 -199
  118. data/doc/RubyProf/CallStackPrinter.html +0 -1127
  119. data/doc/RubyProf/CallTreePrinter.html +0 -725
  120. data/doc/RubyProf/Cmd.html +0 -637
  121. data/doc/RubyProf/DeprecationWarnings.html +0 -148
  122. data/doc/RubyProf/DotPrinter.html +0 -258
  123. data/doc/RubyProf/FlatPrinter.html +0 -164
  124. data/doc/RubyProf/FlatPrinterWithLineNumbers.html +0 -210
  125. data/doc/RubyProf/GraphHtmlPrinter.html +0 -558
  126. data/doc/RubyProf/GraphPrinter.html +0 -140
  127. data/doc/RubyProf/MethodInfo.html +0 -676
  128. data/doc/RubyProf/MultiPrinter.html +0 -574
  129. data/doc/RubyProf/Profile.html +0 -908
  130. data/doc/RubyProf/Profile/ExcludeCommonMethods.html +0 -411
  131. data/doc/RubyProf/Profile/LegacyMethodElimination.html +0 -158
  132. data/doc/RubyProf/ProfileTask.html +0 -491
  133. data/doc/RubyProf/Thread.html +0 -275
  134. data/doc/created.rid +0 -33
  135. data/doc/css/fonts.css +0 -167
  136. data/doc/css/rdoc.css +0 -590
  137. data/doc/examples/flat_txt.html +0 -139
  138. data/doc/examples/graph_html.html +0 -910
  139. data/doc/examples/graph_txt.html +0 -248
  140. data/doc/fonts/Lato-Light.ttf +0 -0
  141. data/doc/fonts/Lato-LightItalic.ttf +0 -0
  142. data/doc/fonts/Lato-Regular.ttf +0 -0
  143. data/doc/fonts/Lato-RegularItalic.ttf +0 -0
  144. data/doc/fonts/SourceCodePro-Bold.ttf +0 -0
  145. data/doc/fonts/SourceCodePro-Regular.ttf +0 -0
  146. data/doc/images/add.png +0 -0
  147. data/doc/images/arrow_up.png +0 -0
  148. data/doc/images/brick.png +0 -0
  149. data/doc/images/brick_link.png +0 -0
  150. data/doc/images/bug.png +0 -0
  151. data/doc/images/bullet_black.png +0 -0
  152. data/doc/images/bullet_toggle_minus.png +0 -0
  153. data/doc/images/bullet_toggle_plus.png +0 -0
  154. data/doc/images/date.png +0 -0
  155. data/doc/images/delete.png +0 -0
  156. data/doc/images/find.png +0 -0
  157. data/doc/images/loadingAnimation.gif +0 -0
  158. data/doc/images/macFFBgHack.png +0 -0
  159. data/doc/images/package.png +0 -0
  160. data/doc/images/page_green.png +0 -0
  161. data/doc/images/page_white_text.png +0 -0
  162. data/doc/images/page_white_width.png +0 -0
  163. data/doc/images/plugin.png +0 -0
  164. data/doc/images/ruby.png +0 -0
  165. data/doc/images/tag_blue.png +0 -0
  166. data/doc/images/tag_green.png +0 -0
  167. data/doc/images/transparent.png +0 -0
  168. data/doc/images/wrench.png +0 -0
  169. data/doc/images/wrench_orange.png +0 -0
  170. data/doc/images/zoom.png +0 -0
  171. data/doc/index.html +0 -666
  172. data/doc/js/darkfish.js +0 -161
  173. data/doc/js/jquery.js +0 -4
  174. data/doc/js/navigation.js +0 -142
  175. data/doc/js/navigation.js.gz +0 -0
  176. data/doc/js/search.js +0 -109
  177. data/doc/js/search_index.js +0 -1
  178. data/doc/js/search_index.js.gz +0 -0
  179. data/doc/js/searcher.js +0 -229
  180. data/doc/js/searcher.js.gz +0 -0
  181. data/doc/table_of_contents.html +0 -1052
  182. data/examples/cachegrind.out.1 +0 -114
  183. data/examples/cachegrind.out.1.32313213 +0 -114
  184. data/ext/ruby_prof/vc/ruby_prof_18.vcxproj +0 -108
  185. data/ext/ruby_prof/vc/ruby_prof_19.vcxproj +0 -110
data/doc/examples/graph_txt.html DELETED
@@ -1,248 +0,0 @@
1
- <!DOCTYPE html>
2
-
3
- <html>
4
- <head>
5
- <meta charset="UTF-8">
6
-
7
- <title>graph - ruby-prof</title>
8
-
9
- <script type="text/javascript">
10
- var rdoc_rel_prefix = "../";
11
- var index_rel_prefix = "../";
12
- </script>
13
-
14
- <script src="../js/jquery.js"></script>
15
- <script src="../js/darkfish.js"></script>
16
-
17
- <link href="../css/fonts.css" rel="stylesheet">
18
- <link href="../css/rdoc.css" rel="stylesheet">
19
-
20
-
21
-
22
- <body id="top" role="document" class="file">
23
- <nav role="navigation">
24
- <div id="project-navigation">
25
- <div id="home-section" role="region" title="Quick navigation" class="nav-section">
26
- <h2>
27
- <a href="../index.html" rel="home">Home</a>
28
- </h2>
29
-
30
- <div id="table-of-contents-navigation">
31
- <a href="../table_of_contents.html#pages">Pages</a>
32
- <a href="../table_of_contents.html#classes">Classes</a>
33
- <a href="../table_of_contents.html#methods">Methods</a>
34
- </div>
35
- </div>
36
-
37
- <div id="search-section" role="search" class="project-section initially-hidden">
38
- <form action="#" method="get" accept-charset="utf-8">
39
- <div id="search-field-wrapper">
40
- <input id="search-field" role="combobox" aria-label="Search"
41
- aria-autocomplete="list" aria-controls="search-results"
42
- type="text" name="search" placeholder="Search" spellcheck="false"
43
- title="Type to search, Up and Down to navigate, Enter to load">
44
- </div>
45
-
46
- <ul id="search-results" aria-label="Search Results"
47
- aria-busy="false" aria-expanded="false"
48
- aria-atomic="false" class="initially-hidden"></ul>
49
- </form>
50
- </div>
51
-
52
- </div>
53
-
54
-
55
- <div class="nav-section">
56
- <h3>Table of Contents</h3>
57
-
58
- <ul class="link-list" role="directory">
59
- <li><a href="#label-Graph+Profiles">Graph Profiles</a>
60
- <li><a href="#label-Overview">Overview</a>
61
- <li><a href="#label-Parents">Parents</a>
62
- <li><a href="#label-Children">Children</a>
63
- </ul>
64
- </div>
65
-
66
-
67
- <div id="project-metadata">
68
- <div id="fileindex-section" class="nav-section">
69
- <h3>Pages</h3>
70
-
71
- <ul class="link-list">
72
-
73
- <li><a href="../LICENSE.html">LICENSE</a>
74
-
75
- <li><a href="../README_rdoc.html">README</a>
76
-
77
- <li><a href="../examples/flat_txt.html">flat</a>
78
-
79
- <li><a href="../examples/graph_html.html">graph.html</a>
80
-
81
- <li><a href="../examples/graph_txt.html">graph</a>
82
-
83
- </ul>
84
- </div>
85
-
86
- </div>
87
- </nav>
88
-
89
- <main role="main" aria-label="Page examples/graph.txt">
90
-
91
- <h1 id="label-Graph+Profiles">Graph Profiles<span><a href="#label-Graph+Profiles">&para;</a> <a href="#top">&uarr;</a></span></h1>
92
-
93
- <p>Graph profiles show how long each method runs, which methods call it and
94
- which methods it calls.</p>
95
-
96
- <p>As an example, here is the output from running printers_test.rb:</p>
97
-
98
- <p>Measure Mode: wall_time Thread ID: 70310439543100 Fiber ID: 70310456289620
99
- Total Time: 0.05264616012573242 Sort by: total_time</p>
100
-
101
- <pre>%total %self total self wait child calls name</pre>
102
- <hr>
103
-
104
- <pre>100.00% 0.01% 0.053 0.000 0.000 0.053 1 PrintersTest#setup
105
- 0.053 0.000 0.000 0.053 1/1 Object#run_primes</pre>
106
- <hr>
107
-
108
- <pre> 0.053 0.000 0.000 0.053 1/1 PrintersTest#setup
109
- 99.99% 0.01% 0.053 0.000 0.000 0.053 1 Object#run_primes
110
- 0.052 0.000 0.000 0.052 1/1 Object#find_primes
111
- 0.001 0.000 0.000 0.001 1/1 Object#make_random_array
112
- 0.000 0.000 0.000 0.000 1/1 Object#find_largest</pre>
113
- <hr>
114
-
115
- <pre> 0.052 0.000 0.000 0.052 1/1 Object#run_primes
116
- 98.35% 0.00% 0.052 0.000 0.000 0.052 1 Object#find_primes
117
- 0.052 0.000 0.000 0.051 1/1 Array#select</pre>
118
- <hr>
119
-
120
- <pre> 0.052 0.000 0.000 0.051 1/1 Object#find_primes
121
- 98.34% 0.61% 0.052 0.000 0.000 0.051 1 Array#select
122
- 0.051 0.000 0.000 0.051 1000/1000 Object#is_prime</pre>
123
- <hr>
124
-
125
- <pre> 0.051 0.000 0.000 0.051 1000/1000 Array#select
126
- 97.74% 0.93% 0.051 0.000 0.000 0.051 1000 Object#is_prime
127
- 0.051 0.051 0.000 0.000 1000/1001 Integer#upto</pre>
128
- <hr>
129
-
130
- <pre> 0.000 0.000 0.000 0.000 1/1001 Object#find_largest
131
- 0.051 0.051 0.000 0.000 1000/1001 Object#is_prime
132
- 96.91% 96.91% 0.051 0.051 0.000 0.000 1001 Integer#upto</pre>
133
- <hr>
134
-
135
- <pre> 0.001 0.000 0.000 0.001 1/1 Object#run_primes
136
- 1.51% 0.00% 0.001 0.000 0.000 0.001 1 Object#make_random_array
137
- 0.001 0.000 0.000 0.000 1/1 Array#each_index
138
- 0.000 0.000 0.000 0.000 1/1 Class#new</pre>
139
- <hr>
140
-
141
- <pre> 0.001 0.000 0.000 0.000 1/1 Object#make_random_array
142
- 1.50% 0.56% 0.001 0.000 0.000 0.000 1 Array#each_index
143
- 0.000 0.000 0.000 0.000 1000/1000 Kernel#rand</pre>
144
- <hr>
145
-
146
- <pre> 0.000 0.000 0.000 0.000 1000/1000 Array#each_index
147
- 0.94% 0.72% 0.000 0.000 0.000 0.000 1000 Kernel#rand
148
- 0.000 0.000 0.000 0.000 1000/1000 Kernel#respond_to_missing?</pre>
149
- <hr>
150
-
151
- <pre> 0.000 0.000 0.000 0.000 1000/1000 Kernel#rand
152
- 0.22% 0.22% 0.000 0.000 0.000 0.000 1000 Kernel#respond_to_missing?</pre>
153
- <hr>
154
-
155
- <pre> 0.000 0.000 0.000 0.000 1/1 Object#run_primes
156
- 0.12% 0.02% 0.000 0.000 0.000 0.000 1 Object#find_largest
157
- 0.000 0.000 0.000 0.000 1/1001 Integer#upto
158
- 0.000 0.000 0.000 0.000 1/1 Array#first</pre>
159
- <hr>
160
-
161
- <pre> 0.000 0.000 0.000 0.000 1/1 Object#make_random_array
162
- 0.01% 0.00% 0.000 0.000 0.000 0.000 1 Class#new
163
- 0.000 0.000 0.000 0.000 1/1 Array#initialize</pre>
164
- <hr>
165
-
166
- <pre> 0.000 0.000 0.000 0.000 1/1 Class#new
167
- 0.01% 0.01% 0.000 0.000 0.000 0.000 1 Array#initialize</pre>
168
- <hr>
169
-
170
- <pre> 0.000 0.000 0.000 0.000 1/1 Object#find_largest
171
- 0.00% 0.00% 0.000 0.000 0.000 0.000 1 Array#first</pre>
172
-
173
- <h2 id="label-Overview">Overview<span><a href="#label-Overview">&para;</a> <a href="#top">&uarr;</a></span></h2>
174
-
175
- <p>Dashed lines divide the report into entries, with one entry per method.
176
- Entries are sorted by total time which is the time spent in the method plus
177
- its children.</p>
178
-
179
- <p>Each entry has a primary line demarked by values in the %total and %self
180
- columns. The primary line represents the method being profiled. Lines
181
- above it are the methods that called this method (parents) while the lines
182
- below it are the methods it called (children).</p>
183
-
184
- <p>All values are in seconds. For the primary line, the columns represent:</p>
185
-
186
- <pre>%total - The percentage of time spent in this method and its children
187
- %self - The percentage of time spent in this method
188
- total - The time spent in this method and its children.
189
- self - The time spent in this method.
190
- wait - The time spent waiting for other threads in this method.
191
- child - The time spent in this method&#39;s children.
192
- calls - The number of times this method was called.
193
- name - The name of the method.</pre>
194
-
195
- <p>The interpretation of method names is:</p>
196
-
197
- <pre>MyObject#test - An instance method &quot;test&quot; of the class &quot;MyObject&quot;
198
- &lt;Object:MyObject&gt;#test - The &lt;&gt; characters indicate a singleton method on a singleton class.</pre>
199
-
200
- <p>For example, we see that 97.74% of the time was spent in Object#is_prime
201
- and its children. Of that time, almost everything was contributed by
202
- Integer#upto. Overall, Integer#upto was called 1001 times and 1000 of those
203
- calls were made by Object#is_prime.</p>
204
-
205
- <h2 id="label-Parents">Parents<span><a href="#label-Parents">&para;</a> <a href="#top">&uarr;</a></span></h2>
206
-
207
- <p>In each entry, the lines above the primary line are the methods that called
208
- the current method. If the current method is a root method then no parents
209
- are shown.</p>
210
-
211
- <p>For parent lines, the columns represent:</p>
212
-
213
- <pre>total - The time spent in the current method and its children on behalf of the parent method.
214
- self - The time spent in this method on behalf of the parent method.
215
- child - The time spent in this method&#39;s children on behalf of the parent.
216
- wait - The time spent waiting for other threads in this method&#39;s children on behalf of the parent.
217
- calls - The number of times the parent method called the current method vs. the total number of calls of the current method.</pre>
218
-
219
- <p>Looking at the main entry for Integer#upto, we see that it was called 1000
220
- times from Object#is_prime and 1 time from find_largest.</p>
221
-
222
- <h2 id="label-Children">Children<span><a href="#label-Children">&para;</a> <a href="#top">&uarr;</a></span></h2>
223
-
224
- <p>In each entry, the lines below the primary line are the methods that the
225
- current method called. If the current method is a leaf method then no
226
- children are shown.</p>
227
-
228
- <p>For children lines, the columns represent:</p>
229
-
230
- <pre>total - The time spent in the child, and its descendants, on behalf of the current method
231
- self - The time spent in the child on behalf of the current method.
232
- wait - The time spent waiting for other threads in the child&#39;s and its descendants on behalf of the current method.
233
- child - The time spent in the child&#39;s descendants on behalf of the current method.
234
- calls - The number of times the child method was called by the current method vs. the total number of calls of the child method.</pre>
235
-
236
- <p>If we look at the main entry for Objext#run_primes, we see that it called
237
- three other methods - Object#find_primes, Object#make_random_array and
238
- Object#find_largest.</p>
239
- </main>
240
-
241
-
242
-
243
- <footer id="validator-badges" role="contentinfo">
244
- <p><a href="http://validator.w3.org/check/referer">Validate</a>
245
- <p>Generated by <a href="https://rdoc.github.io/rdoc">RDoc</a> 5.1.0.
246
- <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
247
- </footer>
248
-
data/doc/fonts/Lato-Light.ttf DELETED
Binary file
data/doc/fonts/Lato-Regular.ttf DELETED
Binary file
data/doc/images/add.png DELETED
Binary file
data/doc/images/arrow_up.png DELETED
Binary file
data/doc/images/brick.png DELETED
Binary file
data/doc/images/brick_link.png DELETED
Binary file
data/doc/images/bug.png DELETED
Binary file
data/doc/images/bullet_black.png DELETED
Binary file
data/doc/images/date.png DELETED
Binary file
data/doc/images/delete.png DELETED
Binary file
data/doc/images/find.png DELETED
Binary file
data/doc/images/macFFBgHack.png DELETED
Binary file
data/doc/images/package.png DELETED
Binary file
data/doc/images/page_green.png DELETED
Binary file
data/doc/images/plugin.png DELETED
Binary file
data/doc/images/ruby.png DELETED
Binary file
data/doc/images/tag_blue.png DELETED
Binary file
data/doc/images/tag_green.png DELETED
Binary file
data/doc/images/transparent.png DELETED
Binary file
data/doc/images/wrench.png DELETED
Binary file
data/doc/images/wrench_orange.png DELETED
Binary file
data/doc/images/zoom.png DELETED
Binary file
data/doc/index.html DELETED
@@ -1,666 +0,0 @@
1
- <!DOCTYPE html>
2
-
3
- <html>
4
- <head>
5
- <meta charset="UTF-8">
6
-
7
- <title>ruby-prof</title>
8
-
9
- <script type="text/javascript">
10
- var rdoc_rel_prefix = "./";
11
- var index_rel_prefix = "./";
12
- </script>
13
-
14
- <script src="./js/jquery.js"></script>
15
- <script src="./js/darkfish.js"></script>
16
-
17
- <link href="./css/fonts.css" rel="stylesheet">
18
- <link href="./css/rdoc.css" rel="stylesheet">
19
-
20
-
21
-
22
- <body id="top" role="document" class="file">
23
- <nav role="navigation">
24
- <div id="project-navigation">
25
- <div id="home-section" role="region" title="Quick navigation" class="nav-section">
26
- <h2>
27
- <a href="./index.html" rel="home">Home</a>
28
- </h2>
29
-
30
- <div id="table-of-contents-navigation">
31
- <a href="./table_of_contents.html#pages">Pages</a>
32
- <a href="./table_of_contents.html#classes">Classes</a>
33
- <a href="./table_of_contents.html#methods">Methods</a>
34
- </div>
35
- </div>
36
-
37
-
38
- <div id="search-section" role="search" class="project-section initially-hidden">
39
- <form action="#" method="get" accept-charset="utf-8">
40
- <div id="search-field-wrapper">
41
- <input id="search-field" role="combobox" aria-label="Search"
42
- aria-autocomplete="list" aria-controls="search-results"
43
- type="text" name="search" placeholder="Search" spellcheck="false"
44
- title="Type to search, Up and Down to navigate, Enter to load">
45
- </div>
46
-
47
- <ul id="search-results" aria-label="Search Results"
48
- aria-busy="false" aria-expanded="false"
49
- aria-atomic="false" class="initially-hidden"></ul>
50
- </form>
51
- </div>
52
-
53
- </div>
54
-
55
- <div id="project-metadata">
56
- <div id="fileindex-section" class="nav-section">
57
- <h3>Pages</h3>
58
-
59
- <ul class="link-list">
60
-
61
- <li><a href="./LICENSE.html">LICENSE</a>
62
-
63
- <li><a href="./README_rdoc.html">README</a>
64
-
65
- <li><a href="./examples/flat_txt.html">flat</a>
66
-
67
- <li><a href="./examples/graph_html.html">graph.html</a>
68
-
69
- <li><a href="./examples/graph_txt.html">graph</a>
70
-
71
- </ul>
72
- </div>
73
-
74
- <div id="classindex-section" class="nav-section">
75
- <h3>Class and Module Index</h3>
76
-
77
- <ul class="link-list">
78
-
79
- <li><a href="./Rack.html">Rack</a>
80
-
81
- <li><a href="./Rack/RubyProf.html">Rack::RubyProf</a>
82
-
83
- <li><a href="./Rack/RubyProf/RackProfiler.html">Rack::RubyProf::RackProfiler</a>
84
-
85
- <li><a href="./RubyProf.html">RubyProf</a>
86
-
87
- <li><a href="./RubyProf/AbstractPrinter.html">RubyProf::AbstractPrinter</a>
88
-
89
- <li><a href="./RubyProf/AggregateCallInfo.html">RubyProf::AggregateCallInfo</a>
90
-
91
- <li><a href="./RubyProf/CallInfo.html">RubyProf::CallInfo</a>
92
-
93
- <li><a href="./RubyProf/CallInfoPrinter.html">RubyProf::CallInfoPrinter</a>
94
-
95
- <li><a href="./RubyProf/CallInfoVisitor.html">RubyProf::CallInfoVisitor</a>
96
-
97
- <li><a href="./RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>
98
-
99
- <li><a href="./RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>
100
-
101
- <li><a href="./RubyProf/Cmd.html">RubyProf::Cmd</a>
102
-
103
- <li><a href="./RubyProf/DeprecationWarnings.html">RubyProf::DeprecationWarnings</a>
104
-
105
- <li><a href="./RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>
106
-
107
- <li><a href="./RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>
108
-
109
- <li><a href="./RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
110
-
111
- <li><a href="./RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
112
-
113
- <li><a href="./RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
114
-
115
- <li><a href="./RubyProf/MethodInfo.html">RubyProf::MethodInfo</a>
116
-
117
- <li><a href="./RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>
118
-
119
- <li><a href="./RubyProf/Profile.html">RubyProf::Profile</a>
120
-
121
- <li><a href="./RubyProf/Profile/ExcludeCommonMethods.html">RubyProf::Profile::ExcludeCommonMethods</a>
122
-
123
- <li><a href="./RubyProf/Profile/LegacyMethodElimination.html">RubyProf::Profile::LegacyMethodElimination</a>
124
-
125
- <li><a href="./RubyProf/ProfileTask.html">RubyProf::ProfileTask</a>
126
-
127
- <li><a href="./RubyProf/Thread.html">RubyProf::Thread</a>
128
-
129
- </ul>
130
- </div>
131
-
132
- </div>
133
- </nav>
134
-
135
- <main role="main">
136
-
137
-
138
- <h1 id="label-ruby-prof">ruby-prof<span><a href="#label-ruby-prof">&para;</a> <a href="#top">&uarr;</a></span></h1>
139
-
140
- <p><a href="https://travis-ci.org/ruby-prof/ruby-prof"><img
141
- src="https://travis-ci.org/ruby-prof/ruby-prof.png?branch=master"
142
- alt="Build Status" /></a></p>
143
-
144
- <h2 id="label-Overview">Overview<span><a href="#label-Overview">&para;</a> <a href="#top">&uarr;</a></span></h2>
145
-
146
- <p>ruby-prof is a fast code profiler for MRI Ruby. Its features include:</p>
147
- <ul><li>
148
- <p>Speed - it is a C extension and therefore many times faster than the
149
- standard Ruby profiler.</p>
150
- </li><li>
151
- <p>Modes - Ruby prof can measure a number of different parameters, including
152
- call times, memory usage and object allocations.</p>
153
- </li><li>
154
- <p>Reports - can generate text and cross-referenced html reports</p>
155
- <ul><li>
156
- <p>Flat Profiles - similar to the reports generated by the standard Ruby
157
- profiler</p>
158
- </li><li>
159
- <p>Graph profiles - similar to GProf, these show how long a method runs, which
160
- methods call it and which methods it calls.</p>
161
- </li><li>
162
- <p>Call tree profiles - outputs results in the calltree format suitable for
163
- the KCacheGrind profiling tool.</p>
164
- </li><li>
165
- <p>Many more – see reports section of this README.</p>
166
- </li></ul>
167
- </li><li>
168
- <p>Threads - supports profiling multiple threads simultaneously</p>
169
- </li></ul>
170
-
171
- <h2 id="label-Requirements">Requirements<span><a href="#label-Requirements">&para;</a> <a href="#top">&uarr;</a></span></h2>
172
-
173
- <p>ruby-prof requires Ruby 1.9.3 or higher. Please note some ruby releases
174
- have known bugs which cause ruby-prof problems, like incorrect
175
- measurements. We suggest to use the latest minor patch level release if
176
- possible. In particular, on the 2.1 branch of ruby you should use at least
177
- 2.1.7.</p>
178
-
179
- <p>If you are running Linux or Unix you&#39;ll need a C compiler so the
180
- extension can be compiled when it is installed.</p>
181
-
182
- <p>If you are running Windows, then you may need to install the Windows
183
- specific RubyGem which includes an already built extension (see Install
184
- section).</p>
185
-
186
- <h2 id="label-Install">Install<span><a href="#label-Install">&para;</a> <a href="#top">&uarr;</a></span></h2>
187
-
188
- <p>The easiest way to install ruby-prof is by using Ruby Gems. To install:</p>
189
-
190
- <pre class="ruby"><span class="ruby-identifier">gem</span> <span class="ruby-identifier">install</span> <span class="ruby-identifier">ruby</span><span class="ruby-operator">-</span><span class="ruby-identifier">prof</span>
191
- </pre>
192
-
193
- <p>If you&#39;re on windows then please install the devkit first so that it
194
- can compile.</p>
195
-
196
- <h2 id="label-Usage">Usage<span><a href="#label-Usage">&para;</a> <a href="#top">&uarr;</a></span></h2>
197
-
198
- <p>There are three major options for running ruby-prof: via the command line,
199
- via its convenience API or via its core API.</p>
200
-
201
- <h3 id="label-ruby-prof+Executable">ruby-prof Executable<span><a href="#label-ruby-prof+Executable">&para;</a> <a href="#top">&uarr;</a></span></h3>
202
-
203
- <p>The first is to use ruby-prof to run the Ruby program you want to profile.
204
- For more information refer to the documentation of the ruby-prof command:
205
- `$ ruby-prof -h.`</p>
206
-
207
- <h3 id="label-ruby-prof+Convenience+API">ruby-prof Convenience API<span><a href="#label-ruby-prof+Convenience+API">&para;</a> <a href="#top">&uarr;</a></span></h3>
208
-
209
- <p>The second way is to use the ruby-prof convenience API to profile
210
- particular segments of code.</p>
211
-
212
- <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
213
-
214
- <span class="ruby-comment"># profile the code</span>
215
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
216
- <span class="ruby-comment"># ... code to profile ...</span>
217
- <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
218
-
219
- <span class="ruby-comment"># print a flat profile to text</span>
220
- <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>)
221
- <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>)
222
- </pre>
223
-
224
- <p>Alternatively, you can use a block to tell ruby-prof what to profile:</p>
225
-
226
- <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
227
-
228
- <span class="ruby-comment"># profile the code</span>
229
- <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
230
- <span class="ruby-comment"># ... code to profile ...</span>
231
- <span class="ruby-keyword">end</span>
232
-
233
- <span class="ruby-comment"># print a graph profile to text</span>
234
- <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>)
235
- <span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>, {})
236
- </pre>
237
-
238
- <p>ruby-prof also supports pausing and resuming profiling runs.</p>
239
-
240
- <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
241
-
242
- <span class="ruby-comment"># profile the code</span>
243
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
244
- <span class="ruby-comment"># ... code to profile ...</span>
245
-
246
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">pause</span>
247
- <span class="ruby-comment"># ... other code ...</span>
248
-
249
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span>
250
- <span class="ruby-comment"># ... code to profile ...</span>
251
- <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
252
- </pre>
253
-
254
- <p>Note that resume will only work if start has been called previously. In
255
- addition, resume can also take a block:</p>
256
-
257
- <pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
258
-
259
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span> <span class="ruby-keyword">do</span>
260
- <span class="ruby-comment"># ... code to profile...</span>
261
- <span class="ruby-keyword">end</span>
262
-
263
- <span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
264
- </pre>
265
-
266
- <p>With this usage, resume will automatically call pause at the end of the
267
- block.</p>
268
-
269
- <h3 id="label-Profiling+Selected+Threads+-28Core+API-29">Profiling Selected Threads (Core API)<span><a href="#label-Profiling+Selected+Threads+-28Core+API-29">&para;</a> <a href="#top">&uarr;</a></span></h3>
270
-
271
- <p>The convenience API does not support running multiple profiles in separate
272
- threads concurrently, but the <a
273
- href="RubyProf/Profile.html">RubyProf::Profile</a> API does. In fact, the
274
- convenience layer uses the Profile API internally. It all revolves around
275
- Profile objects:</p>
276
- <dl class="rdoc-list note-list"><dt><a href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>
277
- <dd>
278
- <p>Create a profile object given an options hash (see below)</p>
279
-
280
- <p>The following options are available when creating Profile instances:</p>
281
- <dl class="rdoc-list note-list"><dt>measure_mode
282
- <dd>
283
- <p>One of the defined measure modes</p>
284
- </dd><dt>exclude_threads
285
- <dd>
286
- <p>Array of threads which should not be profiled.</p>
287
- </dd><dt>include_threads
288
- <dd>
289
- <p>Array of threads which should be profiled. All other threads will be
290
- ignored.</p>
291
- </dd><dt>merge_fibers
292
- <dd>
293
- <p>Whether profiling data for a given thread&#39;s fibers should all be
294
- subsumed under a single entry. Basically only useful to produce callgrind
295
- profiles.</p>
296
- </dd></dl>
297
- </dd><dt><a href="RubyProf/Profile.html#method-i-start">RubyProf::Profile#start</a>
298
- <dd>
299
- <p>Start profiling</p>
300
- </dd><dt><a href="RubyProf/Profile.html#method-i-pause">RubyProf::Profile#pause</a>
301
- <dd>
302
- <p>Pause profiling</p>
303
- </dd><dt><a href="RubyProf/Profile.html#method-i-resume">RubyProf::Profile#resume</a>
304
- <dd>
305
- <p>Resume profiling</p>
306
- </dd><dt><a href="RubyProf/Profile.html#method-i-stop">RubyProf::Profile#stop</a>
307
- <dd>
308
- <p>Stop profiling and return self</p>
309
- </dd><dt><a href="RubyProf/Profile.html#method-i-profile">RubyProf::Profile#profile</a>
310
- <dd>
311
- <p>Perform a profile run and return result. Accepts the same arguments as <a
312
- href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>.</p>
313
- </dd></dl>
314
-
315
- <h2 id="label-Method+Elimination+-28Deprecated-29">Method Elimination (Deprecated)<span><a href="#label-Method+Elimination+-28Deprecated-29">&para;</a> <a href="#top">&uarr;</a></span></h2>
316
-
317
- <p>ruby-prof supports eliminating specific methods and threads from profiling
318
- results. This is useful for reducing connectivity in the call graph, making
319
- it easier to identify the source of performance problems when using a graph
320
- printer.</p>
321
-
322
- <p>For example, consider <code>Integer#times</code>: it&#39;s hardly ever
323
- useful to know how much time is spent in the method itself. We&#39;re much
324
- more interested in how much the passed in block contributes to the time
325
- spent in the method which contains the <code>Integer#times</code> call.</p>
326
-
327
- <p>Methods are eliminated from the collected data by calling
328
- <code>eliminate_methods!</code> on the profiling result, before submitting
329
- it to a printer.</p>
330
-
331
- <pre class="ruby"><span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
332
- <span class="ruby-identifier">result</span>.<span class="ruby-identifier">eliminate_methods!</span>([<span class="ruby-node">/Integer#times/</span>])
333
- </pre>
334
-
335
- <p>The argument given to <code>eliminate_methods!</code> is either an array of
336
- regular expressions, or the name of a file containing a list of regular
337
- expressions (line separated text).</p>
338
-
339
- <p>After eliminating methods the resulting profile will appear exactly as if
340
- those methods had been inlined at their call sites.</p>
341
-
342
- <h2 id="label-Method+Exclusion">Method Exclusion<span><a href="#label-Method+Exclusion">&para;</a> <a href="#top">&uarr;</a></span></h2>
343
-
344
- <p>ruby-prof supports exluding methods from profiling. The effect on collected
345
- metrics are identical to eliminating methods from the profiling result in a
346
- prost process step. The interface is slightly different though:</p>
347
-
348
- <pre>profile = RubyProf.new(...)
349
- profile.exclude_methods!(Integer, :times, ...)
350
- profile.start</pre>
351
-
352
- <p>A convenience method is provided to exclude a large number of methods which
353
- usually clutter up profiles:</p>
354
-
355
- <pre class="ruby"><span class="ruby-identifier">profile</span>.<span class="ruby-identifier">exclude_common_methods!</span>
356
- </pre>
357
-
358
- <p>However, this is a somewhat opinionated method collection. It&#39;s usually
359
- better to view it as an inspiration instead of using it directly (see <a
360
- href="https://github.com/ruby-prof/ruby-prof/blob/e087b7d7ca11eecf1717d95a5c5fea1e36ea3136/lib/ruby-prof/profile/exclude_common_methods.rb">github.com/ruby-prof/ruby-prof/blob/e087b7d7ca11eecf1717d95a5c5fea1e36ea3136/lib/ruby-prof/profile/exclude_common_methods.rb</a>).</p>
361
-
362
- <h2 id="label-Profiling+Rails">Profiling Rails<span><a href="#label-Profiling+Rails">&para;</a> <a href="#top">&uarr;</a></span></h2>
363
-
364
- <p>To profile a Rails application it is vital to run it using production like
365
- settings (cache classes, cache view lookups, etc.). Otherwise, Rail&#39;s
366
- dependency loading code will overwhelm any time spent in the application
367
- itself (our tests show that Rails dependency loading causes a roughly 6x
368
- slowdown). The best way to do this is create a new Rails environment,
369
- profile.rb.</p>
370
-
371
- <p>So to profile Rails:</p>
372
- <ol><li>
373
- <p>Create a new profile.rb environment. Make sure to turn on
374
- <code>cache_classes</code> and <code>cache_template_loading</code>.
375
- Otherwise your profiling results will be overwhelmed by the time Rails
376
- spends loading required files. You should likely turn off caching.</p>
377
- </li><li>
378
- <p>Add the ruby-prof to your gemfile:</p>
379
-
380
- <pre class="ruby"><span class="ruby-identifier">group</span> :<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
381
- <span class="ruby-identifier">gem</span> <span class="ruby-string">&#39;ruby-prof&#39;</span>
382
- <span class="ruby-keyword">end</span>
383
- </pre>
384
- </li><li>
385
- <p>Add the ruby prof rack adapter to your middleware stack. One way to do
386
- this is by adding the following code to <code>config.ru</code>:</p>
387
-
388
- <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>
389
- <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">&#39;/temp/profile&#39;</span>
390
- <span class="ruby-keyword">end</span>
391
- </pre>
392
-
393
- <p>The path is where you want profiling results to be stored. By default the
394
- rack adapter will generate a html call graph report and flat text report.</p>
395
- </li><li>
396
- <p>Now make a request to your running server. New profiling information will
397
- be generated for each request. Note that each request will overwrite the
398
- profiling reports created by the previous request!</p>
399
- </li></ol>
400
-
401
- <h2 id="label-Reports">Reports<span><a href="#label-Reports">&para;</a> <a href="#top">&uarr;</a></span></h2>
402
-
403
- <p>ruby-prof can generate a number of different reports:</p>
404
- <ul><li>
405
- <p>Flat Reports</p>
406
- </li><li>
407
- <p>Graph Reports</p>
408
- </li><li>
409
- <p>HTML Graph Reports</p>
410
- </li><li>
411
- <p>Call graphs</p>
412
- </li><li>
413
- <p>Call stack reports</p>
414
- </li><li>
415
- <p>More!</p>
416
- </li></ul>
417
-
418
- <p>Flat profiles show the overall time spent in each method. They are a good
419
- way of quickly identifying which methods take the most time. An example of
420
- a flat profile and an explanation can be found in <a
421
- href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt">examples/flat.txt</a>.</p>
422
-
423
- <p>There are several varieties of these - run <code>ruby-prof --help</code></p>
424
-
425
- <p>Graph profiles also show the overall time spent in each method. In
426
- addition, they also show which methods call the current method and which
427
- methods its calls. Thus they are good for understanding how methods gets
428
- called and provide insight into the flow of your program. An example text
429
- graph profile is located at <a
430
- href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.txt">examples/graph.txt</a>.</p>
431
-
432
- <p>HTML Graph profiles are the same as graph profiles, except output is
433
- generated in hyper-linked HTML. Since graph profiles can be quite large,
434
- the embedded links make it much easier to navigate the results. An example
435
- html graph profile is located at <a
436
- href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.html">examples/graph.html</a>.</p>
437
-
438
- <p>Call graphs output results in the calltree profile format which is used by
439
- KCachegrind. Call graph support was generously donated by Carl Shimer. More
440
- information about the format can be found at the <a
441
- href="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat">KCachegrind</a>
442
- site.</p>
443
-
444
- <p>Call stack reports produce a HTML visualization of the time spent in each
445
- execution path of the profiled code. An example can be found at <a
446
- href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html">examples/stack.html</a>.</p>
447
-
448
- <p>Another good example: <a
449
- href="http://twitpic.com/28z94a">twitpic.com/28z94a</a></p>
450
-
451
- <p>Finally, there&#39;s a so called MultiPrinter which can generate several
452
- reports in one profiling run. See <a
453
- href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/multi.stack.html">examples/multi.stack.html</a>.</p>
454
-
455
- <p>There is also a graphviz .dot visualiser.</p>
456
-
457
- <h2 id="label-Printers">Printers<span><a href="#label-Printers">&para;</a> <a href="#top">&uarr;</a></span></h2>
458
-
459
- <p>Reports are created by printers. Supported printers include:</p>
460
- <dl class="rdoc-list note-list"><dt><a href="RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>
461
- <dd>
462
- <p>Creates a flat report in text format</p>
463
- </dd><dt><a href="RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
464
- <dd>
465
- <p>Same as above but more verbose</p>
466
- </dd><dt><a href="RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
467
- <dd>
468
- <p>Creates a call graph report in text format</p>
469
- </dd><dt><a href="RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
470
- <dd>
471
- <p>Creates a call graph report in HTML (separate files per thread)</p>
472
- </dd><dt><a href="RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>
473
- <dd>
474
- <p>Creates a call graph report in GraphViz&#39;s DOT format which can be
475
- converted to an image</p>
476
- </dd><dt><a href="RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>
477
- <dd>
478
- <p>Creates a call tree report compatible with KCachegrind</p>
479
- </dd><dt><a href="RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>
480
- <dd>
481
- <p>Creates a HTML visualization of the Ruby stack</p>
482
- </dd><dt><a href="RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>
483
- <dd>
484
- <p>Uses the other printers to create several reports in one profiling run</p>
485
- </dd></dl>
486
-
487
- <p>Most printers are used in the following way:</p>
488
-
489
- <pre class="ruby"><span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
490
- <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>)
491
- <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>)
492
- </pre>
493
-
494
- <p>The first parameter is any writable IO object such as <code>STDOUT</code>
495
- or a file. The second parameter, specifies the minimum percentage a method
496
- must take to be printed. Percentages should be specified as integers in
497
- the range 0 to 100. For more information please see the documentation for
498
- the different printers.</p>
499
-
500
- <p>The other option is <code>:print_file =&gt; true</code> (default false),
501
- which adds the filename to the output (GraphPrinter only).</p>
502
-
503
- <p><code>MultiPrinter</code> and <code>CallTreePrinter</code>differ from the
504
- other printers in that they require a directory path and a profile basename
505
- for the files they produce:</p>
506
-
507
- <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>)
508
- <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>)
509
- </pre>
510
-
511
- <p>The values given in the example above are the defaults.</p>
512
-
513
- <h2 id="label-Measurements">Measurements<span><a href="#label-Measurements">&para;</a> <a href="#top">&uarr;</a></span></h2>
514
-
515
- <p>Depending on the mode and platform, ruby-prof can measure various aspects
516
- of a Ruby program. Supported measurements include:</p>
517
- <dl class="rdoc-list note-list"><dt>RubyProf::WALL_TIME
518
- <dd>
519
- <p>Wall time measures the real-world time elapsed between any two moments. If
520
- there are other processes concurrently running on the system that use
521
- significant CPU or disk time during a profiling run then the reported
522
- results will be larger than expected.</p>
523
- </dd><dt>RubyProf::PROCESS_TIME
524
- <dd>
525
- <p>Process time measures the time used by a process between any two moments.
526
- It is unaffected by other processes concurrently running on the system.
527
- Note that Windows does not support measuring process times.</p>
528
- </dd><dt>RubyProf::CPU_TIME
529
- <dd>
530
- <p>CPU time uses the CPU clock counter to measure time. The returned values
531
- are dependent on the correctly setting the CPU&#39;s frequency. This mode
532
- is only supported on Pentium or PowerPC platforms (linux only).</p>
533
- </dd><dt>RubyProf::ALLOCATIONS
534
- <dd>
535
- <p>Object allocation reports show how many objects each method in a program
536
- allocates. This support was added by Sylvain Joyeux and requires a patched
537
- Ruby interpreter. See below.</p>
538
- </dd><dt>RubyProf::MEMORY
539
- <dd>
540
- <p>Memory usage reports show how much memory each method in a program uses.
541
- This support was added by Alexander Dymo and requires a patched Ruby
542
- interpreter. See below.</p>
543
- </dd><dt>RubyProf::GC_TIME
544
- <dd>
545
- <p>Garbage collection time reports how much time is spent in Ruby&#39;s
546
- garbage collector during a profiling session. This support was added by
547
- Jeremy Kemper and requires a patched Ruby interpreter. See below.</p>
548
- </dd><dt>RubyProf::GC_RUNS
549
- <dd>
550
- <p>Garbage collection runs report how many times Ruby&#39;s garbage collector
551
- is invoked during a profiling session. This support was added by Jeremy
552
- Kemper and requires a patched Ruby interpreter. See below.</p>
553
- </dd></dl>
554
-
555
- <h2 id="label-Patching+ruby">Patching ruby<span><a href="#label-Patching+ruby">&para;</a> <a href="#top">&uarr;</a></span></h2>
556
-
557
- <p>All of the patches to Ruby are included in the railsexpress patchsets for
558
- rvm, see <a
559
- href="https://github.com/skaes/rvm-patchsets">github.com/skaes/rvm-patchsets</a>.
560
- You can also use these patches manually with other ruby managers
561
- (ruby-install, ruby-build, etc.).</p>
562
-
563
- <p>Note if you rebuild your ruby with patches you must uninstall and reinstall
564
- the ruby-prof gem to take advantage of the new capabilities.</p>
565
-
566
- <h2 id="label-Measure+modes">Measure modes<span><a href="#label-Measure+modes">&para;</a> <a href="#top">&uarr;</a></span></h2>
567
-
568
- <p>To set the measurement:</p>
569
-
570
- <pre class="ruby"><span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">WALL_TIME</span>
571
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">PROCESS_TIME</span>
572
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">CPU_TIME</span>
573
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOCATIONS</span>
574
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">MEMORY</span>
575
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GC_TIME</span>
576
- <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GC_RUNS</span>
577
- </pre>
578
-
579
- <p>The default value is <code>RubyProf::WALL_TIME</code>.</p>
580
-
581
- <p>You may also specify the measure mode by using the
582
- <code>RUBY_PROF_MEASURE_MODE</code> environment variable:</p>
583
-
584
- <pre class="ruby"><span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">wall</span>
585
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">process</span>
586
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">cpu</span>
587
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">allocations</span>
588
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">memory</span>
589
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">gc_time</span>
590
- <span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">gc_runs</span>
591
- </pre>
592
-
593
- <p>On Linux, process time is measured using the clock method provided by the C
594
- runtime library. Note that the clock method does not report time spent in
595
- the kernel or child processes and therefore does not measure time spent in
596
- methods such as Kernel.sleep method. If you need to measure these values,
597
- then use wall time. Wall time is measured using the gettimeofday kernel
598
- method.</p>
599
-
600
- <p>If you set the clock mode to <code>PROCESS_TIME</code>, then timings are
601
- read using the clock method provided by the C runtime library. Note
602
- though, these values are wall times on Windows and not process times like
603
- on Linux. Wall time is measured using the GetLocalTime API.</p>
604
-
605
- <p>If you use wall time, the results will be affected by other processes
606
- running on your computer, network delays, disk access, etc. As result, for
607
- the best results, try to make sure your computer is only performing your
608
- profiling run and is otherwise quiescent.</p>
609
-
610
- <h2 id="label-Multi-threaded+Applications">Multi-threaded Applications<span><a href="#label-Multi-threaded+Applications">&para;</a> <a href="#top">&uarr;</a></span></h2>
611
-
612
- <p>Unfortunately, Ruby does not provide an internal API for detecting thread
613
- context switches. As a result, the timings ruby-prof reports for each
614
- thread may be slightly inaccurate. In particular, this will happen for
615
- newly spawned threads that go to sleep immediately (their first call). For
616
- instance, if you use Ruby&#39;s timeout library to wait for 2 seconds, the
617
- 2 seconds will be assigned to the foreground thread and not the newly
618
- created background thread. These errors can largely be avoided if the
619
- background thread performs any operation before going to sleep.</p>
620
-
621
- <h2 id="label-Performance">Performance<span><a href="#label-Performance">&para;</a> <a href="#top">&uarr;</a></span></h2>
622
-
623
- <p>Significant effort has been put into reducing ruby-prof&#39;s overhead as
624
- much as possible. Our tests show that the overhead associated with
625
- profiling code varies considerably with the code being profiled. Most
626
- programs will run approximately twice as slow while highly recursive
627
- programs (like the fibonacci series test) will run three times slower.</p>
628
-
629
- <h2 id="label-Editing+links">Editing links<span><a href="#label-Editing+links">&para;</a> <a href="#top">&uarr;</a></span></h2>
630
-
631
- <p>Use <code>RUBY_PROF_EDITOR_URI</code> environment variable to open source
632
- code files in your favorite text editor. For example,
633
- <code>RUBY_PROF_EDITOR_URI=atm</code> will produce links for Atom text
634
- editor.</p>
635
-
636
- <h2 id="label-License">License<span><a href="#label-License">&para;</a> <a href="#top">&uarr;</a></span></h2>
637
-
638
- <p>See <a href="LICENSE.html">LICENSE</a> for license information.</p>
639
-
640
- <h2 id="label-API+Documentation">API Documentation<span><a href="#label-API+Documentation">&para;</a> <a href="#top">&uarr;</a></span></h2>
641
-
642
- <p>The ruby-prof API documentation for the latest released gem version can be
643
- found here: <a
644
- href="http://www.rubydoc.info/gems/ruby-prof">www.rubydoc.info/gems/ruby-prof</a>/</p>
645
-
646
- <p>The ruby-prof API documentation for the master branch is available here: <a
647
- href="http://www.rubydoc.info/github/ruby-prof/ruby-prof">www.rubydoc.info/github/ruby-prof/ruby-prof</a>/</p>
648
-
649
- <h2 id="label-Development">Development<span><a href="#label-Development">&para;</a> <a href="#top">&uarr;</a></span></h2>
650
-
651
- <p>Code is located at <a
652
- href="https://github.com/ruby-prof/ruby-prof">github.com/ruby-prof/ruby-prof</a></p>
653
-
654
- <p>Google group/mailing list: <a
655
- href="http://groups.google.com/group/ruby-optimization">groups.google.com/group/ruby-optimization</a>
656
- or open a github issue.</p>
657
- </main>
658
-
659
-
660
-
661
- <footer id="validator-badges" role="contentinfo">
662
- <p><a href="http://validator.w3.org/check/referer">Validate</a>
663
- <p>Generated by <a href="https://rdoc.github.io/rdoc">RDoc</a> 5.1.0.
664
- <p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
665
- </footer>
666
-