| blob | 81b5d7739cd08a0ef8f29cf775ca1a2184a5d7ba |
2 <html>
3 <head>
10 </head>
11 <body>
14 </div>
17 </div>
19 <ul><li>
21 <ul><li>
23 </li><li>
25 </li><li>
27 </li></ul>
28 </li><li>
30 <ul><li>
32 <ul><li>
34 </li><li>
36 </li><li>
38 </li></ul>
39 </li><li>
41 </li><li>
43 </li><li>
45 </li><li>
47 </li></ul>
48 </li><li>
50 </li><li>
52 </li><li>
54 </li></ul>
55 </div>
57 <p>
58 LuaJIT has an integrated statistical profiler with very low overhead. It
59 allows sampling the currently executing stack and other parameters in
60 regular intervals.
61 </p>
62 <p>
63 The integrated profiler can be accessed from three levels:
64 </p>
65 <ul>
70 </ul>
73 <p>
74 The bundled high-level profiler offers basic profiling functionality. It
75 generates simple textual summaries or source code annotations. It can be
78 </p>
79 <p>
80 To cut to the chase — run this to get a CPU usage profile by
81 function name:
82 </p>
84 luajit -jp myapp.lua
85 </pre>
86 <p>
88 possible option or to cater for special profiling needs. The low-level
89 profiler APIs are documented below. They may be used by third-party
90 authors to implement advanced functionality, e.g. IDE integration or
91 graphical profilers.
92 </p>
93 <p>
94 Note: Sampling works for both interpreted and JIT-compiled code. The
95 results for JIT-compiled code may sometimes be surprising. LuaJIT
96 heavily optimizes and inlines Lua code — there's no simple
97 one-to-one correspondence between source code lines and the sampled
98 machine code.
99 </p>
102 <p>
104 When the application run by the command line terminates, the profiler
107 </p>
108 <p>
110 performed:
111 </p>
112 <ul>
114 This is the default mode.</li>
134 Note: The actual sampling precision is OS-dependent.</li>
135 </ul>
136 <p>
138 spots in the application. Increasing the stack dump depth with (say)
140 hotspots. But sample aggregation is still flat per unique stack dump.
141 </p>
142 <p>
143 To get a two-level view (split view) of callers/callees, use
145 level are relative to the first level.
146 </p>
147 <p>
148 To see how much time is spent in each line relative to a function, use
150 </p>
151 <p>
152 To see how much time is spent in different VM states or
154 </p>
155 <p>
158 spent in a VM state or zone vs. hotspots. This can be used to answer
159 questions like "Which time-consuming functions are only interpreted?" or
160 "What's the garbage collector overhead for a specific function?".
161 </p>
162 <p>
163 Multiple options can be combined — but not all combinations make
165 deep in 4ms intervals and shows a split view of the CPU consuming
166 functions and their callers with a 1% threshold.
167 </p>
168 <p>
170 always flat and at the line level. Obviously, the source code files need
171 to be readable by the profiler script.
172 </p>
173 <p>
174 The high-level profiler can also be started and stopped from Lua code with:
175 </p>
177 require("jit.p").start(options, output)
178 ...
179 require("jit.p").stop()
180 </pre>
183 <p>
184 Zones can be used to provide information about different parts of an
185 application to the high-level profiler. E.g. a game could make use of an
187 organized as a stack.
188 </p>
189 <p>
191 </p>
193 local zone = require("jit.zone")
194 </pre>
195 <ul>
198 returns its name.</li>
201 </ul>
202 <p>
205 </p>
208 <p>
210 profiler from Lua code. This module needs to be loaded explicitly:
212 local profile = require("jit.profile")
213 </pre>
214 <p>
215 This module can be used to implement your own higher-level profiler.
216 A typical profiling run starts the profiler, captures stack dumps in
217 the profiler callback, adds them to a hash table to aggregate the number
218 of samples, stops the profiler and then analyzes all captured
219 stack dumps. Other parameters can be sampled in the profiler callback,
220 too. But it's important not to spend too much time in the callback,
221 since this may skew the statistics.
222 </p>
226 <p>
228 string holding options:
229 </p>
230 <ul>
235 Note: The actual sampling precision is OS-dependent.
236 </li>
237 </ul>
238 <p>
242 state that holds the stack to sample for profiling. Note: do
244 </p>
245 <p>
247 callback (usually 1).
248 </p>
249 <p>
251 triggered. This may or may not correspond to the state of the VM when
255 compiler.
256 </p>
260 <p>
261 This function stops the profiler.
262 </p>
266 <p>
267 This function allows taking stack dumps in an efficient manner. It
270 </p>
271 <ul>
273 only the file name is used.</li>
275 use module:line.</li>
279 frame.</li>
281 </ul>
282 <p>
284 at the topmost frame of the thread. A negative number dumps the frames in
285 inverse order.
286 </p>
287 <p>
288 The first example prints a list of the current module names and line
289 numbers of up to 10 frames in separate lines. The second example prints
290 semicolon-separated function names for all frames (up to 100) in inverse
291 order:
292 </p>
296 </pre>
299 <p>
300 The profiler can be controlled directly from C code, e.g. for
303 </p>
307 <p>
310 </p>
311 <p>
313 declaration:
314 </p>
316 typedef void (*luaJIT_profile_callback)(void *data, lua_State *L,
317 int samples, int vmstate);
318 </pre>
319 <p>
321 state that holds the stack to sample for profiling. Note: do
325 </p>
329 <p>
330 This function stops the profiler.
331 </p>
335 <p>
336 This function allows taking stack dumps in an efficient manner.
339 </p>
340 <p>
343 argument returns the length of the output string. The buffer is
344 overwritten on the next call and deallocated when the profiler stops.
345 You either need to consume the content immediately or copy it for later
346 use.
347 </p>
349 </div>
354 ·
356 </span>
357 </div>
358 </body>
359 </html>