ruby-prof 0.16.2 → 1.1.0

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