Commit | Line | Data |
---|---|---|
53f60086 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
a0acfc98 | 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
53f60086 RS |
4 | @c See the file elisp.texi for copying conditions. |
5 | @setfilename ../info/compile | |
969fe9b5 | 6 | @node Byte Compilation, Advising, Loading, Top |
53f60086 RS |
7 | @chapter Byte Compilation |
8 | @cindex byte-code | |
9 | @cindex compilation | |
10 | ||
969fe9b5 | 11 | Emacs Lisp has a @dfn{compiler} that translates functions written |
53f60086 RS |
12 | in Lisp into a special representation called @dfn{byte-code} that can be |
13 | executed more efficiently. The compiler replaces Lisp function | |
14 | definitions with byte-code. When a byte-code function is called, its | |
15 | definition is evaluated by the @dfn{byte-code interpreter}. | |
16 | ||
17 | Because the byte-compiled code is evaluated by the byte-code | |
18 | interpreter, instead of being executed directly by the machine's | |
19 | hardware (as true compiled code is), byte-code is completely | |
20 | transportable from machine to machine without recompilation. It is not, | |
21 | however, as fast as true compiled code. | |
22 | ||
23 | In general, any version of Emacs can run byte-compiled code produced | |
969fe9b5 RS |
24 | by recent earlier versions of Emacs, but the reverse is not true. A |
25 | major incompatible change was introduced in Emacs version 19.29, and | |
26 | files compiled with versions since that one will definitely not run | |
27 | in earlier versions unless you specify a special option. | |
bfe721d1 KH |
28 | @iftex |
29 | @xref{Docs and Compilation}. | |
30 | @end iftex | |
969fe9b5 RS |
31 | In addition, the modifier bits in keyboard characters were renumbered in |
32 | Emacs 19.29; as a result, files compiled in versions before 19.29 will | |
33 | not work in subsequent versions if they contain character constants with | |
34 | modifier bits. | |
53f60086 RS |
35 | |
36 | @xref{Compilation Errors}, for how to investigate errors occurring in | |
37 | byte compilation. | |
38 | ||
39 | @menu | |
a0acfc98 | 40 | * Speed of Byte-Code:: An example of speedup from byte compilation. |
53f60086 | 41 | * Compilation Functions:: Byte compilation functions. |
22697dac KH |
42 | * Docs and Compilation:: Dynamic loading of documentation strings. |
43 | * Dynamic Loading:: Dynamic loading of individual functions. | |
53f60086 RS |
44 | * Eval During Compile:: Code to be evaluated when you compile. |
45 | * Byte-Code Objects:: The data type used for byte-compiled functions. | |
46 | * Disassembly:: Disassembling byte-code; how to read byte-code. | |
47 | @end menu | |
48 | ||
a0acfc98 RS |
49 | @node Speed of Byte-Code |
50 | @section Performance of Byte-Compiled Code | |
53f60086 RS |
51 | |
52 | A byte-compiled function is not as efficient as a primitive function | |
53 | written in C, but runs much faster than the version written in Lisp. | |
a0acfc98 | 54 | Here is an example: |
53f60086 RS |
55 | |
56 | @example | |
57 | @group | |
58 | (defun silly-loop (n) | |
59 | "Return time before and after N iterations of a loop." | |
60 | (let ((t1 (current-time-string))) | |
61 | (while (> (setq n (1- n)) | |
62 | 0)) | |
63 | (list t1 (current-time-string)))) | |
64 | @result{} silly-loop | |
65 | @end group | |
66 | ||
67 | @group | |
68 | (silly-loop 100000) | |
a0acfc98 RS |
69 | @result{} ("Fri Mar 18 17:25:57 1994" |
70 | "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} | |
53f60086 RS |
71 | @end group |
72 | ||
73 | @group | |
74 | (byte-compile 'silly-loop) | |
75 | @result{} @r{[Compiled code not shown]} | |
76 | @end group | |
77 | ||
78 | @group | |
79 | (silly-loop 100000) | |
a0acfc98 RS |
80 | @result{} ("Fri Mar 18 17:26:52 1994" |
81 | "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} | |
53f60086 RS |
82 | @end group |
83 | @end example | |
84 | ||
a0acfc98 RS |
85 | In this example, the interpreted code required 31 seconds to run, |
86 | whereas the byte-compiled code required 6 seconds. These results are | |
53f60086 RS |
87 | representative, but actual results will vary greatly. |
88 | ||
a0acfc98 RS |
89 | @node Compilation Functions |
90 | @comment node-name, next, previous, up | |
91 | @section The Compilation Functions | |
92 | @cindex compilation functions | |
93 | ||
94 | You can byte-compile an individual function or macro definition with | |
95 | the @code{byte-compile} function. You can compile a whole file with | |
96 | @code{byte-compile-file}, or several files with | |
97 | @code{byte-recompile-directory} or @code{batch-byte-compile}. | |
98 | ||
9e2b495b RS |
99 | The byte compiler produces error messages and warnings about each file |
100 | in a buffer called @samp{*Compile-Log*}. These report things in your | |
101 | program that suggest a problem but are not necessarily erroneous. | |
a0acfc98 RS |
102 | |
103 | @cindex macro compilation | |
969fe9b5 RS |
104 | Be careful when writing macro calls in files that you may someday |
105 | byte-compile. Macro calls are expanded when they are compiled, so the | |
106 | macros must already be defined for proper compilation. For more | |
107 | details, see @ref{Compiling Macros}. | |
a0acfc98 RS |
108 | |
109 | Normally, compiling a file does not evaluate the file's contents or | |
bfe721d1 KH |
110 | load the file. But it does execute any @code{require} calls at top |
111 | level in the file. One way to ensure that necessary macro definitions | |
112 | are available during compilation is to require the file that defines | |
113 | them (@pxref{Named Features}). To avoid loading the macro definition files | |
114 | when someone @emph{runs} the compiled program, write | |
115 | @code{eval-when-compile} around the @code{require} calls (@pxref{Eval | |
116 | During Compile}). | |
a0acfc98 | 117 | |
53f60086 | 118 | @defun byte-compile symbol |
a0acfc98 | 119 | This function byte-compiles the function definition of @var{symbol}, |
53f60086 RS |
120 | replacing the previous definition with the compiled one. The function |
121 | definition of @var{symbol} must be the actual code for the function; | |
122 | i.e., the compiler does not follow indirection to another symbol. | |
a0acfc98 RS |
123 | @code{byte-compile} returns the new, compiled definition of |
124 | @var{symbol}. | |
125 | ||
22697dac | 126 | If @var{symbol}'s definition is a byte-code function object, |
a0acfc98 RS |
127 | @code{byte-compile} does nothing and returns @code{nil}. Lisp records |
128 | only one function definition for any symbol, and if that is already | |
129 | compiled, non-compiled code is not available anywhere. So there is no | |
130 | way to ``compile the same definition again.'' | |
53f60086 RS |
131 | |
132 | @example | |
133 | @group | |
134 | (defun factorial (integer) | |
135 | "Compute factorial of INTEGER." | |
136 | (if (= 1 integer) 1 | |
137 | (* integer (factorial (1- integer))))) | |
a0acfc98 | 138 | @result{} factorial |
53f60086 RS |
139 | @end group |
140 | ||
141 | @group | |
142 | (byte-compile 'factorial) | |
a0acfc98 | 143 | @result{} |
53f60086 RS |
144 | #[(integer) |
145 | "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" | |
146 | [integer 1 * factorial] | |
147 | 4 "Compute factorial of INTEGER."] | |
148 | @end group | |
149 | @end example | |
150 | ||
151 | @noindent | |
a0acfc98 RS |
152 | The result is a byte-code function object. The string it contains is |
153 | the actual byte-code; each character in it is an instruction or an | |
154 | operand of an instruction. The vector contains all the constants, | |
155 | variable names and function names used by the function, except for | |
156 | certain primitives that are coded as special instructions. | |
53f60086 RS |
157 | @end defun |
158 | ||
159 | @deffn Command compile-defun | |
160 | This command reads the defun containing point, compiles it, and | |
161 | evaluates the result. If you use this on a defun that is actually a | |
162 | function definition, the effect is to install a compiled version of that | |
163 | function. | |
164 | @end deffn | |
165 | ||
166 | @deffn Command byte-compile-file filename | |
a0acfc98 | 167 | This function compiles a file of Lisp code named @var{filename} into |
53f60086 RS |
168 | a file of byte-code. The output file's name is made by appending |
169 | @samp{c} to the end of @var{filename}. | |
170 | ||
a0acfc98 | 171 | Compilation works by reading the input file one form at a time. If it |
53f60086 RS |
172 | is a definition of a function or macro, the compiled function or macro |
173 | definition is written out. Other forms are batched together, then each | |
174 | batch is compiled, and written so that its compiled code will be | |
175 | executed when the file is read. All comments are discarded when the | |
176 | input file is read. | |
177 | ||
a0acfc98 | 178 | This command returns @code{t}. When called interactively, it prompts |
53f60086 RS |
179 | for the file name. |
180 | ||
181 | @example | |
182 | @group | |
183 | % ls -l push* | |
184 | -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
185 | @end group | |
186 | ||
187 | @group | |
188 | (byte-compile-file "~/emacs/push.el") | |
189 | @result{} t | |
190 | @end group | |
191 | ||
192 | @group | |
193 | % ls -l push* | |
194 | -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el | |
195 | -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc | |
196 | @end group | |
197 | @end example | |
198 | @end deffn | |
199 | ||
200 | @deffn Command byte-recompile-directory directory flag | |
201 | @cindex library compilation | |
a0acfc98 | 202 | This function recompiles every @samp{.el} file in @var{directory} that |
53f60086 RS |
203 | needs recompilation. A file needs recompilation if a @samp{.elc} file |
204 | exists but is older than the @samp{.el} file. | |
205 | ||
969fe9b5 RS |
206 | When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag} |
207 | says what to do. If it is @code{nil}, these files are ignored. If it | |
208 | is non-@code{nil}, the user is asked whether to compile each such file. | |
53f60086 | 209 | |
a0acfc98 | 210 | The returned value of this command is unpredictable. |
53f60086 RS |
211 | @end deffn |
212 | ||
213 | @defun batch-byte-compile | |
a0acfc98 RS |
214 | This function runs @code{byte-compile-file} on files specified on the |
215 | command line. This function must be used only in a batch execution of | |
216 | Emacs, as it kills Emacs on completion. An error in one file does not | |
f9f59935 RS |
217 | prevent processing of subsequent files, but no output file will be |
218 | generated for it, and the Emacs process will terminate with a nonzero | |
219 | status code. | |
53f60086 RS |
220 | |
221 | @example | |
222 | % emacs -batch -f batch-byte-compile *.el | |
223 | @end example | |
224 | @end defun | |
225 | ||
226 | @defun byte-code code-string data-vector max-stack | |
227 | @cindex byte-code interpreter | |
a0acfc98 | 228 | This function actually interprets byte-code. A byte-compiled function |
53f60086 | 229 | is actually defined with a body that calls @code{byte-code}. Don't call |
969fe9b5 | 230 | this function yourself---only the byte compiler knows how to generate |
53f60086 RS |
231 | valid calls to this function. |
232 | ||
969fe9b5 RS |
233 | In Emacs version 18, byte-code was always executed by way of a call to |
234 | the function @code{byte-code}. Nowadays, byte-code is usually executed | |
235 | as part of a byte-code function object, and only rarely through an | |
236 | explicit call to @code{byte-code}. | |
53f60086 RS |
237 | @end defun |
238 | ||
22697dac KH |
239 | @node Docs and Compilation |
240 | @section Documentation Strings and Compilation | |
241 | @cindex dynamic loading of documentation | |
242 | ||
243 | Functions and variables loaded from a byte-compiled file access their | |
244 | documentation strings dynamically from the file whenever needed. This | |
cc8c51f1 | 245 | saves space within Emacs, and makes loading faster because the |
22697dac KH |
246 | documentation strings themselves need not be processed while loading the |
247 | file. Actual access to the documentation strings becomes slower as a | |
248 | result, but this normally is not enough to bother users. | |
249 | ||
250 | Dynamic access to documentation strings does have drawbacks: | |
251 | ||
252 | @itemize @bullet | |
253 | @item | |
254 | If you delete or move the compiled file after loading it, Emacs can no | |
255 | longer access the documentation strings for the functions and variables | |
256 | in the file. | |
257 | ||
258 | @item | |
259 | If you alter the compiled file (such as by compiling a new version), | |
260 | then further access to documentation strings in this file will give | |
261 | nonsense results. | |
262 | @end itemize | |
263 | ||
264 | If your site installs Emacs following the usual procedures, these | |
265 | problems will never normally occur. Installing a new version uses a new | |
266 | directory with a different name; as long as the old version remains | |
267 | installed, its files will remain unmodified in the places where they are | |
268 | expected to be. | |
269 | ||
89dbfd18 | 270 | However, if you have built Emacs yourself and use it from the |
22697dac KH |
271 | directory where you built it, you will experience this problem |
272 | occasionally if you edit and recompile Lisp files. When it happens, you | |
273 | can cure the problem by reloading the file after recompiling it. | |
274 | ||
969fe9b5 RS |
275 | Byte-compiled files made with recent versions of Emacs (since 19.29) |
276 | will not load into older versions because the older versions don't | |
277 | support this feature. You can turn off this feature at compile time by | |
278 | setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you | |
279 | can compile files that will load into older Emacs versions. You can do | |
280 | this globally, or for one source file by specifying a file-local binding | |
281 | for the variable. One way to do that is by adding this string to the | |
282 | file's first line: | |
22697dac KH |
283 | |
284 | @example | |
285 | -*-byte-compile-dynamic-docstrings: nil;-*- | |
286 | @end example | |
287 | ||
288 | @defvar byte-compile-dynamic-docstrings | |
289 | If this is non-@code{nil}, the byte compiler generates compiled files | |
290 | that are set up for dynamic loading of documentation strings. | |
291 | @end defvar | |
292 | ||
293 | @cindex @samp{#@@@var{count}} | |
294 | @cindex @samp{#$} | |
295 | The dynamic documentation string feature writes compiled files that | |
296 | use a special Lisp reader construct, @samp{#@@@var{count}}. This | |
297 | construct skips the next @var{count} characters. It also uses the | |
298 | @samp{#$} construct, which stands for ``the name of this file, as a | |
969fe9b5 RS |
299 | string.'' It is usually best not to use these constructs in Lisp source |
300 | files, since they are not designed to be clear to humans reading the | |
301 | file. | |
22697dac KH |
302 | |
303 | @node Dynamic Loading | |
304 | @section Dynamic Loading of Individual Functions | |
305 | ||
306 | @cindex dynamic loading of functions | |
307 | @cindex lazy loading | |
308 | When you compile a file, you can optionally enable the @dfn{dynamic | |
309 | function loading} feature (also known as @dfn{lazy loading}). With | |
310 | dynamic function loading, loading the file doesn't fully read the | |
311 | function definitions in the file. Instead, each function definition | |
312 | contains a place-holder which refers to the file. The first time each | |
313 | function is called, it reads the full definition from the file, to | |
314 | replace the place-holder. | |
315 | ||
316 | The advantage of dynamic function loading is that loading the file | |
317 | becomes much faster. This is a good thing for a file which contains | |
969fe9b5 RS |
318 | many separate user-callable functions, if using one of them does not |
319 | imply you will probably also use the rest. A specialized mode which | |
320 | provides many keyboard commands often has that usage pattern: a user may | |
321 | invoke the mode, but use only a few of the commands it provides. | |
22697dac KH |
322 | |
323 | The dynamic loading feature has certain disadvantages: | |
324 | ||
325 | @itemize @bullet | |
326 | @item | |
327 | If you delete or move the compiled file after loading it, Emacs can no | |
328 | longer load the remaining function definitions not already loaded. | |
329 | ||
330 | @item | |
331 | If you alter the compiled file (such as by compiling a new version), | |
969fe9b5 | 332 | then trying to load any function not already loaded will yield nonsense |
22697dac KH |
333 | results. |
334 | @end itemize | |
335 | ||
969fe9b5 RS |
336 | These problems will never happen in normal circumstances with |
337 | installed Emacs files. But they are quite likely to happen with Lisp | |
338 | files that you are changing. The easiest way to prevent these problems | |
339 | is to reload the new compiled file immediately after each recompilation. | |
22697dac KH |
340 | |
341 | The byte compiler uses the dynamic function loading feature if the | |
342 | variable @code{byte-compile-dynamic} is non-@code{nil} at compilation | |
343 | time. Do not set this variable globally, since dynamic loading is | |
344 | desirable only for certain files. Instead, enable the feature for | |
969fe9b5 RS |
345 | specific source files with file-local variable bindings. For example, |
346 | you could do it by writing this text in the source file's first line: | |
22697dac KH |
347 | |
348 | @example | |
349 | -*-byte-compile-dynamic: t;-*- | |
350 | @end example | |
351 | ||
352 | @defvar byte-compile-dynamic | |
353 | If this is non-@code{nil}, the byte compiler generates compiled files | |
354 | that are set up for dynamic function loading. | |
355 | @end defvar | |
356 | ||
357 | @defun fetch-bytecode function | |
358 | This immediately finishes loading the definition of @var{function} from | |
359 | its byte-compiled file, if it is not fully loaded already. The argument | |
360 | @var{function} may be a byte-code function object or a function name. | |
361 | @end defun | |
362 | ||
53f60086 RS |
363 | @node Eval During Compile |
364 | @section Evaluation During Compilation | |
365 | ||
22697dac | 366 | These features permit you to write code to be evaluated during |
53f60086 RS |
367 | compilation of a program. |
368 | ||
369 | @defspec eval-and-compile body | |
370 | This form marks @var{body} to be evaluated both when you compile the | |
371 | containing code and when you run it (whether compiled or not). | |
372 | ||
373 | You can get a similar result by putting @var{body} in a separate file | |
969fe9b5 RS |
374 | and referring to that file with @code{require}. That method is |
375 | preferable when @var{body} is large. | |
53f60086 RS |
376 | @end defspec |
377 | ||
378 | @defspec eval-when-compile body | |
f9f59935 | 379 | This form marks @var{body} to be evaluated at compile time but not when |
78c71a98 | 380 | the compiled program is loaded. The result of evaluation by the |
f9f59935 RS |
381 | compiler becomes a constant which appears in the compiled program. If |
382 | you load the source file, rather than compiling it, @var{body} is | |
383 | evaluated normally. | |
53f60086 | 384 | |
969fe9b5 RS |
385 | @strong{Common Lisp Note:} At top level, this is analogous to the Common |
386 | Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the | |
387 | Common Lisp @samp{#.} reader macro (but not when interpreting) is closer | |
388 | to what @code{eval-when-compile} does. | |
53f60086 RS |
389 | @end defspec |
390 | ||
391 | @node Byte-Code Objects | |
bfe721d1 | 392 | @section Byte-Code Function Objects |
53f60086 RS |
393 | @cindex compiled function |
394 | @cindex byte-code function | |
395 | ||
396 | Byte-compiled functions have a special data type: they are | |
397 | @dfn{byte-code function objects}. | |
398 | ||
399 | Internally, a byte-code function object is much like a vector; | |
400 | however, the evaluator handles this data type specially when it appears | |
401 | as a function to be called. The printed representation for a byte-code | |
402 | function object is like that for a vector, with an additional @samp{#} | |
403 | before the opening @samp{[}. | |
404 | ||
53f60086 | 405 | A byte-code function object must have at least four elements; there is |
969fe9b5 | 406 | no maximum number, but only the first six elements have any normal use. |
53f60086 RS |
407 | They are: |
408 | ||
409 | @table @var | |
410 | @item arglist | |
411 | The list of argument symbols. | |
412 | ||
413 | @item byte-code | |
414 | The string containing the byte-code instructions. | |
415 | ||
416 | @item constants | |
78c71a98 RS |
417 | The vector of Lisp objects referenced by the byte code. These include |
418 | symbols used as function names and variable names. | |
53f60086 RS |
419 | |
420 | @item stacksize | |
421 | The maximum stack size this function needs. | |
422 | ||
423 | @item docstring | |
bfe721d1 KH |
424 | The documentation string (if any); otherwise, @code{nil}. The value may |
425 | be a number or a list, in case the documentation string is stored in a | |
426 | file. Use the function @code{documentation} to get the real | |
427 | documentation string (@pxref{Accessing Documentation}). | |
53f60086 RS |
428 | |
429 | @item interactive | |
430 | The interactive spec (if any). This can be a string or a Lisp | |
431 | expression. It is @code{nil} for a function that isn't interactive. | |
432 | @end table | |
433 | ||
434 | Here's an example of a byte-code function object, in printed | |
435 | representation. It is the definition of the command | |
436 | @code{backward-sexp}. | |
437 | ||
438 | @example | |
439 | #[(&optional arg) | |
440 | "^H\204^F^@@\301^P\302^H[!\207" | |
441 | [arg 1 forward-sexp] | |
442 | 2 | |
443 | 254435 | |
444 | "p"] | |
445 | @end example | |
446 | ||
447 | The primitive way to create a byte-code object is with | |
448 | @code{make-byte-code}: | |
449 | ||
450 | @defun make-byte-code &rest elements | |
451 | This function constructs and returns a byte-code function object | |
452 | with @var{elements} as its elements. | |
453 | @end defun | |
454 | ||
a0acfc98 RS |
455 | You should not try to come up with the elements for a byte-code |
456 | function yourself, because if they are inconsistent, Emacs may crash | |
78c71a98 | 457 | when you call the function. Always leave it to the byte compiler to |
a0acfc98 | 458 | create these objects; it makes the elements consistent (we hope). |
53f60086 RS |
459 | |
460 | You can access the elements of a byte-code object using @code{aref}; | |
461 | you can also use @code{vconcat} to create a vector with the same | |
462 | elements. | |
463 | ||
464 | @node Disassembly | |
465 | @section Disassembled Byte-Code | |
466 | @cindex disassembled byte-code | |
467 | ||
468 | People do not write byte-code; that job is left to the byte compiler. | |
469 | But we provide a disassembler to satisfy a cat-like curiosity. The | |
470 | disassembler converts the byte-compiled code into humanly readable | |
471 | form. | |
472 | ||
473 | The byte-code interpreter is implemented as a simple stack machine. | |
a0acfc98 | 474 | It pushes values onto a stack of its own, then pops them off to use them |
78c71a98 RS |
475 | in calculations whose results are themselves pushed back on the stack. |
476 | When a byte-code function returns, it pops a value off the stack and | |
477 | returns it as the value of the function. | |
53f60086 | 478 | |
78c71a98 | 479 | In addition to the stack, byte-code functions can use, bind, and set |
a0acfc98 RS |
480 | ordinary Lisp variables, by transferring values between variables and |
481 | the stack. | |
53f60086 RS |
482 | |
483 | @deffn Command disassemble object &optional stream | |
484 | This function prints the disassembled code for @var{object}. If | |
485 | @var{stream} is supplied, then output goes there. Otherwise, the | |
486 | disassembled code is printed to the stream @code{standard-output}. The | |
487 | argument @var{object} can be a function name or a lambda expression. | |
488 | ||
489 | As a special exception, if this function is used interactively, | |
490 | it outputs to a buffer named @samp{*Disassemble*}. | |
491 | @end deffn | |
492 | ||
493 | Here are two examples of using the @code{disassemble} function. We | |
494 | have added explanatory comments to help you relate the byte-code to the | |
495 | Lisp source; these do not appear in the output of @code{disassemble}. | |
496 | These examples show unoptimized byte-code. Nowadays byte-code is | |
497 | usually optimized, but we did not want to rewrite these examples, since | |
498 | they still serve their purpose. | |
499 | ||
500 | @example | |
501 | @group | |
502 | (defun factorial (integer) | |
503 | "Compute factorial of an integer." | |
504 | (if (= 1 integer) 1 | |
505 | (* integer (factorial (1- integer))))) | |
506 | @result{} factorial | |
507 | @end group | |
508 | ||
509 | @group | |
510 | (factorial 4) | |
511 | @result{} 24 | |
512 | @end group | |
513 | ||
514 | @group | |
515 | (disassemble 'factorial) | |
516 | @print{} byte-code for factorial: | |
517 | doc: Compute factorial of an integer. | |
518 | args: (integer) | |
519 | @end group | |
520 | ||
521 | @group | |
522 | 0 constant 1 ; @r{Push 1 onto stack.} | |
523 | ||
524 | 1 varref integer ; @r{Get value of @code{integer}} | |
525 | ; @r{from the environment} | |
526 | ; @r{and push the value} | |
527 | ; @r{onto the stack.} | |
528 | @end group | |
529 | ||
530 | @group | |
531 | 2 eqlsign ; @r{Pop top two values off stack,} | |
532 | ; @r{compare them,} | |
533 | ; @r{and push result onto stack.} | |
534 | @end group | |
535 | ||
536 | @group | |
537 | 3 goto-if-nil 10 ; @r{Pop and test top of stack;} | |
538 | ; @r{if @code{nil}, go to 10,} | |
539 | ; @r{else continue.} | |
540 | @end group | |
541 | ||
542 | @group | |
543 | 6 constant 1 ; @r{Push 1 onto top of stack.} | |
544 | ||
545 | 7 goto 17 ; @r{Go to 17 (in this case, 1 will be} | |
546 | ; @r{returned by the function).} | |
547 | @end group | |
548 | ||
549 | @group | |
550 | 10 constant * ; @r{Push symbol @code{*} onto stack.} | |
551 | ||
552 | 11 varref integer ; @r{Push value of @code{integer} onto stack.} | |
553 | @end group | |
554 | ||
555 | @group | |
556 | 12 constant factorial ; @r{Push @code{factorial} onto stack.} | |
557 | ||
558 | 13 varref integer ; @r{Push value of @code{integer} onto stack.} | |
559 | ||
560 | 14 sub1 ; @r{Pop @code{integer}, decrement value,} | |
561 | ; @r{push new value onto stack.} | |
562 | @end group | |
563 | ||
564 | @group | |
565 | ; @r{Stack now contains:} | |
566 | ; @minus{} @r{decremented value of @code{integer}} | |
567 | ; @minus{} @r{@code{factorial}} | |
568 | ; @minus{} @r{value of @code{integer}} | |
569 | ; @minus{} @r{@code{*}} | |
570 | @end group | |
571 | ||
572 | @group | |
573 | 15 call 1 ; @r{Call function @code{factorial} using} | |
574 | ; @r{the first (i.e., the top) element} | |
575 | ; @r{of the stack as the argument;} | |
576 | ; @r{push returned value onto stack.} | |
577 | @end group | |
578 | ||
579 | @group | |
580 | ; @r{Stack now contains:} | |
78c71a98 | 581 | ; @minus{} @r{result of recursive} |
53f60086 RS |
582 | ; @r{call to @code{factorial}} |
583 | ; @minus{} @r{value of @code{integer}} | |
584 | ; @minus{} @r{@code{*}} | |
585 | @end group | |
586 | ||
587 | @group | |
588 | 16 call 2 ; @r{Using the first two} | |
589 | ; @r{(i.e., the top two)} | |
590 | ; @r{elements of the stack} | |
591 | ; @r{as arguments,} | |
592 | ; @r{call the function @code{*},} | |
593 | ; @r{pushing the result onto the stack.} | |
594 | @end group | |
595 | ||
596 | @group | |
597 | 17 return ; @r{Return the top element} | |
598 | ; @r{of the stack.} | |
599 | @result{} nil | |
600 | @end group | |
601 | @end example | |
602 | ||
603 | The @code{silly-loop} function is somewhat more complex: | |
604 | ||
605 | @example | |
606 | @group | |
607 | (defun silly-loop (n) | |
608 | "Return time before and after N iterations of a loop." | |
609 | (let ((t1 (current-time-string))) | |
610 | (while (> (setq n (1- n)) | |
611 | 0)) | |
612 | (list t1 (current-time-string)))) | |
613 | @result{} silly-loop | |
614 | @end group | |
615 | ||
616 | @group | |
617 | (disassemble 'silly-loop) | |
618 | @print{} byte-code for silly-loop: | |
619 | doc: Return time before and after N iterations of a loop. | |
620 | args: (n) | |
621 | ||
622 | 0 constant current-time-string ; @r{Push} | |
623 | ; @r{@code{current-time-string}} | |
624 | ; @r{onto top of stack.} | |
625 | @end group | |
626 | ||
627 | @group | |
628 | 1 call 0 ; @r{Call @code{current-time-string}} | |
629 | ; @r{ with no argument,} | |
630 | ; @r{ pushing result onto stack.} | |
631 | @end group | |
632 | ||
633 | @group | |
634 | 2 varbind t1 ; @r{Pop stack and bind @code{t1}} | |
635 | ; @r{to popped value.} | |
636 | @end group | |
637 | ||
638 | @group | |
639 | 3 varref n ; @r{Get value of @code{n} from} | |
640 | ; @r{the environment and push} | |
641 | ; @r{the value onto the stack.} | |
642 | @end group | |
643 | ||
644 | @group | |
645 | 4 sub1 ; @r{Subtract 1 from top of stack.} | |
646 | @end group | |
647 | ||
648 | @group | |
649 | 5 dup ; @r{Duplicate the top of the stack;} | |
a0acfc98 | 650 | ; @r{i.e., copy the top of} |
53f60086 RS |
651 | ; @r{the stack and push the} |
652 | ; @r{copy onto the stack.} | |
653 | @end group | |
654 | ||
655 | @group | |
656 | 6 varset n ; @r{Pop the top of the stack,} | |
657 | ; @r{and bind @code{n} to the value.} | |
658 | ||
659 | ; @r{In effect, the sequence @code{dup varset}} | |
660 | ; @r{copies the top of the stack} | |
661 | ; @r{into the value of @code{n}} | |
662 | ; @r{without popping it.} | |
663 | @end group | |
664 | ||
665 | @group | |
666 | 7 constant 0 ; @r{Push 0 onto stack.} | |
667 | @end group | |
668 | ||
669 | @group | |
670 | 8 gtr ; @r{Pop top two values off stack,} | |
671 | ; @r{test if @var{n} is greater than 0} | |
672 | ; @r{and push result onto stack.} | |
673 | @end group | |
674 | ||
675 | @group | |
78c71a98 RS |
676 | 9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} |
677 | ; @r{(this exits the while loop).} | |
53f60086 RS |
678 | ; @r{else pop top of stack} |
679 | ; @r{and continue} | |
53f60086 RS |
680 | @end group |
681 | ||
682 | @group | |
683 | 12 constant nil ; @r{Push @code{nil} onto stack} | |
684 | ; @r{(this is the body of the loop).} | |
685 | @end group | |
686 | ||
687 | @group | |
688 | 13 discard ; @r{Discard result of the body} | |
689 | ; @r{of the loop (a while loop} | |
690 | ; @r{is always evaluated for} | |
691 | ; @r{its side effects).} | |
692 | @end group | |
693 | ||
694 | @group | |
695 | 14 goto 3 ; @r{Jump back to beginning} | |
696 | ; @r{of while loop.} | |
697 | @end group | |
698 | ||
699 | @group | |
700 | 17 discard ; @r{Discard result of while loop} | |
701 | ; @r{by popping top of stack.} | |
78c71a98 RS |
702 | ; @r{This result is the value @code{nil} that} |
703 | ; @r{was not popped by the goto at 9.} | |
53f60086 RS |
704 | @end group |
705 | ||
706 | @group | |
707 | 18 varref t1 ; @r{Push value of @code{t1} onto stack.} | |
708 | @end group | |
709 | ||
710 | @group | |
711 | 19 constant current-time-string ; @r{Push} | |
712 | ; @r{@code{current-time-string}} | |
713 | ; @r{onto top of stack.} | |
714 | @end group | |
715 | ||
716 | @group | |
717 | 20 call 0 ; @r{Call @code{current-time-string} again.} | |
718 | @end group | |
719 | ||
720 | @group | |
721 | 21 list2 ; @r{Pop top two elements off stack,} | |
722 | ; @r{create a list of them,} | |
723 | ; @r{and push list onto stack.} | |
724 | @end group | |
725 | ||
726 | @group | |
727 | 22 unbind 1 ; @r{Unbind @code{t1} in local environment.} | |
728 | ||
729 | 23 return ; @r{Return value of the top of stack.} | |
730 | ||
731 | @result{} nil | |
732 | @end group | |
733 | @end example | |
734 | ||
735 |