Debian Codegraph @

upstream/debian-unstable/man1/perlinterp.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLINTERP 1"
58 .TH PERLINTERP 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlinterp \- An overview of the Perl interpreter
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 This document provides an overview of how the Perl interpreter works at
68 the level of C code, along with pointers to the relevant C source code
69 files.
70 .SH "ELEMENTS OF THE INTERPRETER"
71 .IX Header "ELEMENTS OF THE INTERPRETER"
72 The work of the interpreter has two main stages: compiling the code
73 into the internal representation, or bytecode, and then executing it.
74 "Compiled code" in perlguts explains exactly how the compilation stage
75 happens.
76 .PP
77 Here is a short breakdown of perl's operation:
78 .SS Startup
79 .IX Subsection "Startup"
80 The action begins in \fIperlmain.c\fR. (or \fIminiperlmain.c\fR for miniperl)
81 This is very high-level code, enough to fit on a single screen, and it
82 resembles the code found in perlembed; most of the real action takes
83 place in \fIperl.c\fR
84 .PP
85 \&\fIperlmain.c\fR is generated by \f(CW\*(C`ExtUtils::Miniperl\*(C'\fR from
86 \&\fIminiperlmain.c\fR at make time, so you should make perl to follow this
87 along.
88 .PP
89 First, \fIperlmain.c\fR allocates some memory and constructs a Perl
90 interpreter, along these lines:
91 .PP
92 .Vb 9
93 \& 1 PERL_SYS_INIT3(&argc,&argv,&env);
94 \& 2
95 \& 3 if (!PL_do_undump) {
96 \& 4 my_perl = perl_alloc();
97 \& 5 if (!my_perl)
98 \& 6 exit(1);
99 \& 7 perl_construct(my_perl);
100 \& 8 PL_perl_destruct_level = 0;
101 \& 9 }
102 .Ve
103 .PP
104 Line 1 is a macro, and its definition is dependent on your operating
105 system. Line 3 references \f(CW\*(C`PL_do_undump\*(C'\fR, a global variable \- all
106 global variables in Perl start with \f(CW\*(C`PL_\*(C'\fR. This tells you whether the
107 current running program was created with the \f(CW\*(C`\-u\*(C'\fR flag to perl and
108 then \fIundump\fR, which means it's going to be false in any sane context.
109 .PP
110 Line 4 calls a function in \fIperl.c\fR to allocate memory for a Perl
111 interpreter. It's quite a simple function, and the guts of it looks
112 like this:
113 .PP
114 .Vb 1
115 \& my_perl = (PerlInterpreter*)PerlMem_malloc(sizeof(PerlInterpreter));
116 .Ve
117 .PP
118 Here you see an example of Perl's system abstraction, which we'll see
119 later: \f(CW\*(C`PerlMem_malloc\*(C'\fR is either your system's \f(CW\*(C`malloc\*(C'\fR, or Perl's
120 own \f(CW\*(C`malloc\*(C'\fR as defined in \fImalloc.c\fR if you selected that option at
121 configure time.
122 .PP
123 Next, in line 7, we construct the interpreter using perl_construct,
124 also in \fIperl.c\fR; this sets up all the special variables that Perl
125 needs, the stacks, and so on.
126 .PP
127 Now we pass Perl the command line options, and tell it to go:
128 .PP
129 .Vb 2
130 \& if (!perl_parse(my_perl, xs_init, argc, argv, (char **)NULL))
131 \& perl_run(my_perl);
132 \&
133 \& exitstatus = perl_destruct(my_perl);
134 \&
135 \& perl_free(my_perl);
136 .Ve
137 .PP
138 \&\f(CW\*(C`perl_parse\*(C'\fR is actually a wrapper around \f(CW\*(C`S_parse_body\*(C'\fR, as defined
139 in \fIperl.c\fR, which processes the command line options, sets up any
140 statically linked XS modules, opens the program and calls \f(CW\*(C`yyparse\*(C'\fR to
141 parse it.
142 .SS Parsing
143 .IX Subsection "Parsing"
144 The aim of this stage is to take the Perl source, and turn it into an
145 op tree. We'll see what one of those looks like later. Strictly
146 speaking, there's three things going on here.
147 .PP
148 \&\f(CW\*(C`yyparse\*(C'\fR, the parser, lives in \fIperly.c\fR, although you're better off
149 reading the original YACC input in \fIperly.y\fR. (Yes, Virginia, there
150 \&\fBis\fR a YACC grammar for Perl!) The job of the parser is to take your
151 code and "understand" it, splitting it into sentences, deciding which
152 operands go with which operators and so on.
153 .PP
154 The parser is nobly assisted by the lexer, which chunks up your input
155 into tokens, and decides what type of thing each token is: a variable
156 name, an operator, a bareword, a subroutine, a core function, and so
157 on. The main point of entry to the lexer is \f(CW\*(C`yylex\*(C'\fR, and that and its
158 associated routines can be found in \fItoke.c\fR. Perl isn't much like
159 other computer languages; it's highly context sensitive at times, it
160 can be tricky to work out what sort of token something is, or where a
161 token ends. As such, there's a lot of interplay between the tokeniser
162 and the parser, which can get pretty frightening if you're not used to
163 it.
164 .PP
165 As the parser understands a Perl program, it builds up a tree of
166 operations for the interpreter to perform during execution. The
167 routines which construct and link together the various operations are
168 to be found in \fIop.c\fR, and will be examined later.
169 .SS Optimization
170 .IX Subsection "Optimization"
171 Now the parsing stage is complete, and the finished tree represents the
172 operations that the Perl interpreter needs to perform to execute our
173 program. Next, Perl does a dry run over the tree looking for
174 optimisations: constant expressions such as \f(CW\*(C`3 + 4\*(C'\fR will be computed
175 now, and the optimizer will also see if any multiple operations can be
176 replaced with a single one. For instance, to fetch the variable
177 \&\f(CW$foo\fR, instead of grabbing the glob \f(CW*foo\fR and looking at the scalar
178 component, the optimizer fiddles the op tree to use a function which
179 directly looks up the scalar in question. The main optimizer is \f(CW\*(C`peep\*(C'\fR
180 in \fIop.c\fR, and many ops have their own optimizing functions.
181 .SS Running
182 .IX Subsection "Running"
183 Now we're finally ready to go: we have compiled Perl byte code, and all
184 that's left to do is run it. The actual execution is done by the
185 \&\f(CW\*(C`runops_standard\*(C'\fR function in \fIrun.c\fR; more specifically, it's done
186 by these three innocent looking lines:
187 .PP
188 .Vb 3
189 \& while ((PL_op = PL_op\->op_ppaddr(aTHX))) {
190 \& PERL_ASYNC_CHECK();
191 \& }
192 .Ve
193 .PP
194 You may be more comfortable with the Perl version of that:
195 .PP
196 .Vb 1
197 \& PERL_ASYNC_CHECK() while $Perl::op = &{$Perl::op\->{function}};
198 .Ve
199 .PP
200 Well, maybe not. Anyway, each op contains a function pointer, which
201 stipulates the function which will actually carry out the operation.
202 This function will return the next op in the sequence \- this allows for
203 things like \f(CW\*(C`if\*(C'\fR which choose the next op dynamically at run time. The
204 \&\f(CW\*(C`PERL_ASYNC_CHECK\*(C'\fR makes sure that things like signals interrupt
205 execution if required.
206 .PP
207 The actual functions called are known as PP code, and they're spread
208 between four files: \fIpp_hot.c\fR contains the "hot" code, which is most
209 often used and highly optimized, \fIpp_sys.c\fR contains all the
210 system-specific functions, \fIpp_ctl.c\fR contains the functions which
211 implement control structures (\f(CW\*(C`if\*(C'\fR, \f(CW\*(C`while\*(C'\fR and the like) and \fIpp.c\fR
212 contains everything else. These are, if you like, the C code for Perl's
213 built-in functions and operators.
214 .PP
215 Note that each \f(CW\*(C`pp_\*(C'\fR function is expected to return a pointer to the
216 next op. Calls to perl subs (and eval blocks) are handled within the
217 same runops loop, and do not consume extra space on the C stack. For
218 example, \f(CW\*(C`pp_entersub\*(C'\fR and \f(CW\*(C`pp_entertry\*(C'\fR just push a \f(CW\*(C`CXt_SUB\*(C'\fR or
219 \&\f(CW\*(C`CXt_EVAL\*(C'\fR block struct onto the context stack, which contain the address
220 of the op following the sub call or eval. They then return the first op
221 of that sub or eval block, and so execution continues of that sub or
222 block. Later, a \f(CW\*(C`pp_leavesub\*(C'\fR or \f(CW\*(C`pp_leavetry\*(C'\fR op pops the \f(CW\*(C`CXt_SUB\*(C'\fR
223 or \f(CW\*(C`CXt_EVAL\*(C'\fR, retrieves the return op from it, and returns it.
224 .SS "Exception handing"
225 .IX Subsection "Exception handing"
226 Perl's exception handing (i.e. \f(CW\*(C`die\*(C'\fR etc.) is built on top of the
227 low-level \f(CWsetjmp()\fR/\f(CWlongjmp()\fR C\-library functions. These basically
228 provide a way to capture the current PC and SP registers of the CPU and
229 later restore them: i.e. a \f(CWlongjmp()\fR continues at the point in code
230 where a previous \f(CWsetjmp()\fR was done, with anything further up on the C
231 stack being lost. (This is why code should always save values using
232 \&\f(CW\*(C`SAVE_\fR\f(CIFOO\fR\f(CW\*(C'\fR rather than in auto variables.)
233 .PP
234 The perl core wraps \f(CWsetjmp()\fR and \f(CWlongjmp()\fR in the macros
235 \&\f(CW\*(C`JMPENV_PUSH\*(C'\fR and \f(CW\*(C`JMPENV_JUMP\*(C'\fR. The push operation, as well as setting
236 a \f(CWsetjump()\fR, stores some temporary state in a struct local to the
237 current function (allocated by \f(CW\*(C`dJMPENV\*(C'\fR). In particular, it stores a
238 pointer to the previous \f(CW\*(C`JMPENV\*(C'\fR struct, and updates \f(CW\*(C`PL_top_env\*(C'\fR to
239 point to the newest one, forming a chain of \f(CW\*(C`JMPENV\*(C'\fR states. Both the
240 push and jump can output debugging information under \f(CW\*(C`perl \-Dl\*(C'\fR.
241 .PP
242 A basic rule of the perl internals is that all interpreter exits are
243 achieved via a \f(CWJMPENV_JUMP()\fR. In particular:
244 .IP \(bu 4
245 level 2: perl-level \fBexit()\fR and internals \fBmy_exit()\fR
246 .Sp
247 These unwind all stacks, then perform a \fBJMPENV_JUMP\fR\|(2).
248 .IP \(bu 4
249 level 3: perl-level \fBdie()\fR and internals \fBcroak()\fR
250 .Sp
251 If currently within an eval, these pop the context stack back to the
252 nearest \f(CW\*(C`CXt_EVAL\*(C'\fR frame, set \f(CW$@\fR as appropriate, set \f(CW\*(C`PL_restartop\*(C'\fR
253 to the op which follows the eval associated with that frame, then perform
254 a \fBJMPENV_JUMP\fR\|(3).
255 .Sp
256 Otherwise, the error message is printed to \f(CW\*(C`STDERR\*(C'\fR, then it is treated
257 as an exit: unwind all stacks and perform a \fBJMPENV_JUMP\fR\|(2).
258 .IP \(bu 4
259 level 1: unused
260 .Sp
261 \&\fBJMPENV_JUMP\fR\|(1) is currently unused except in \fBperl_run()\fR.
262 .IP \(bu 4
263 level 0: normal return.
264 .Sp
265 The zero value is for a normal return from \fBJMPENV_PUSH()\fR
266 .PP
267 So the perl interpreter expects that, at all times, there is a suitable
268 \&\f(CW\*(C`JMPENV_PUSH\*(C'\fR set up (and at a suitable location within the CPU call
269 stack) that can catch and process a 2\- or 3\-valued jump; and in the case
270 of a 3, start a new runops loop to execute \f(CW\*(C`PL_restartop\*(C'\fR and all
271 remaining ops (as will be explained shortly).
272 .PP
273 The entry points to the perl interpreter all provide such a facility. For
274 example, \fBperl_parse()\fR, \fBperl_run()\fR and \f(CW\*(C`call_sv(cv, G_EVAL)\*(C'\fR all contain
275 something similar in outline to:
276 .PP
277 .Vb 10
278 \& {
279 \& dJMPENV;
280 \& JMPENV_PUSH(ret);
281 \& switch (ret) {
282 \& case 0: /* normal return from JMPENV_PUSH() */
283 \& redo_body:
284 \& CALLRUNOPS(aTHX);
285 \& break;
286 \& case 2: /* caught longjmp(2) \- exit / die */
287 \& break;
288 \& case 3: /* caught longjmp(3) \- eval { die } */
289 \& PL_op = PL_restartop;
290 \& goto redo_body;
291 \& }
292 \&
293 \& JMPENV_POP;
294 \& }
295 .Ve
296 .PP
297 A runops loop such as \fBPerl_runops_standard()\fR (as set up by \fBCALLRUNOPS()\fR)
298 is, at its heart, just a simple:
299 .PP
300 .Vb 1
301 \& while ((PL_op = PL_op\->op_ppaddr(aTHX))) { 1; }
302 .Ve
303 .PP
304 which calls the \fBpp()\fR function associated with each op, relying on that to
305 return a pointer to the next op to be executed.
306 .PP
307 As well as setting catches at the entry points to the perl interpreter,
308 you might expect perl to also do a \fBJMPENV_PUSH()\fR in places like
309 \&\fBpp_entertry()\fR, just before some trappable ops are executed. In fact perl
310 doesn't normally do this. The drawback with doing it is that with nested
311 or recursive code such as:
312 .PP
313 .Vb 1
314 \& sub foo { my ($i) = @_; return if $i < 0; eval { foo(\-\-$i) } }
315 .Ve
316 .PP
317 Then the C stack would quickly overflow with pairs of entries like
318 .PP
319 .Vb 6
320 \& ...
321 \& #N+3 Perl_runops()
322 \& #N+2 Perl_pp_entertry()
323 \& #N+1 Perl_runops()
324 \& #N Perl_pp_entertry()
325 \& ...
326 .Ve
327 .PP
328 Instead, perl puts its guards at the \fIcallers\fR of runops loops. Then as
329 many nested subroutine calls and evals may be called as you like, all
330 within the one runops loop. If an exception occurs, control passes back to
331 the caller of the loop, which just immediately restarts a new loop with
332 \&\f(CW\*(C`PL_restartop\*(C'\fR being the next op to call.
333 .PP
334 So in normal operation where there are several nested evals, there
335 will be multiple \f(CW\*(C`CXt_EVAL\*(C'\fR context stack entries, but only a single
336 runops loop, guarded by a single \f(CW\*(C`JMPENV_PUSH\*(C'\fR. Each caught eval will pop
337 the next \f(CW\*(C`CXt_EVAL\*(C'\fR off the stack, set \f(CW\*(C`PL_restartop\*(C'\fR, then \fBlongjmp()\fR
338 back to \fBperl_run()\fR and continue.
339 .PP
340 However, ops are sometimes executed within an inner runops loop, such as
341 in a tie, sort, or overload code. In this case, something like
342 .PP
343 .Vb 1
344 \& sub FETCH { eval { die }; .... }
345 .Ve
346 .PP
347 would, unless handled specially, cause a \fBlongjmp()\fR right back to the guard
348 in \fBperl_run()\fR, popping \fIboth\fR the runops loops \- which is clearly
349 incorrect. One way to avoid this is for the tie code to do a
350 \&\f(CW\*(C`JMPENV_PUSH\*(C'\fR before executing \f(CW\*(C`FETCH\*(C'\fR in the inner runops loop, but for
351 efficiency reasons, perl in fact just temporarily sets a flag using
352 \&\f(CWCATCH_SET(TRUE)\fR. This flag warns any subsequent \f(CW\*(C`require\*(C'\fR,
353 \&\f(CW\*(C`entereval\*(C'\fR or \f(CW\*(C`entertry\*(C'\fR ops that the caller is no longer promising to
354 catch any raised exceptions on their behalf.
355 .PP
356 These ops check this flag, and if true, they (via \fBdocatch()\fR) do a
357 \&\f(CW\*(C`JMPENV_PUSH\*(C'\fR and start a new runops loop to execute the code, rather
358 than doing it with the current loop.
359 .PP
360 As a consequence, on exit from the eval block in the \f(CW\*(C`FETCH\*(C'\fR above,
361 execution of the code following the block is still carried on in the
362 inner loop (i.e. the one established by the \fBpp_entertry()\fR). To avoid
363 confusion, if a further exception is then raised, \fBdocatch()\fR compares the
364 \&\f(CW\*(C`JMPENV\*(C'\fR level of the \f(CW\*(C`CXt_EVAL\*(C'\fR with \f(CW\*(C`PL_top_env\*(C'\fR and if they differ,
365 just re-throws the exception. In this way any inner loops get popped,
366 and the exception will be dealt with properly by the level which is
367 expecting it.
368 .PP
369 Here's an example.
370 .PP
371 .Vb 5
372 \& 1: eval { tie @a, \*(AqA\*(Aq };
373 \& 2: sub A::TIEARRAY {
374 \& 3: eval { die };
375 \& 4: die;
376 \& 5: }
377 .Ve
378 .PP
379 To run this code, \fBperl_run()\fR is called, which does a \fBJMPENV_PUSH()\fR,
380 then enters a runops loop. This loop executes the \f(CW\*(C`entereval\*(C'\fR and \f(CW\*(C`tie\*(C'\fR
381 ops on line 1, with the \f(CW\*(C`entereval\*(C'\fR pushing a \f(CW\*(C`CXt_EVAL\*(C'\fR onto the context
382 stack.
383 .PP
384 The \fBpp_tie()\fR does a \f(CWCATCH_SET(TRUE)\fR, then starts a second runops
385 loop to execute the body of \fBTIEARRAY()\fR. When the loop executes the
386 \&\f(CW\*(C`entertry\*(C'\fR op on line 3, \fBCATCH_GET()\fR is true, so \fBpp_entertry()\fR calls
387 \&\fBdocatch()\fR which does a \f(CW\*(C`JMPENV_PUSH\*(C'\fR and starts a third runops loop,
388 which restarts the \fBpp_entertry()\fR, then executes the \f(CW\*(C`die\*(C'\fR op. At this
389 point the C call stack looks like this:
390 .PP
391 .Vb 11
392 \& #10 Perl_pp_die()
393 \& #9 Perl_runops() # runops loop 3
394 \& #8 S_docatch() # JMPENV level 2
395 \& #7 Perl_pp_entertry()
396 \& #6 Perl_runops() # runops loop 2
397 \& #5 Perl_call_sv()
398 \& #4 Perl_pp_tie()
399 \& #3 Perl_runops() # runops loop 1
400 \& #2 S_run_body()
401 \& #1 perl_run() # JMPENV level 1
402 \& #0 main()
403 .Ve
404 .PP
405 and the context and data stacks, as shown by \f(CW\*(C`perl \-Dstv\*(C'\fR, look like:
406 .PP
407 .Vb 9
408 \& STACK 0: MAIN
409 \& CX 0: BLOCK =>
410 \& CX 1: EVAL => AV() PV("A"\e0)
411 \& retop=leave
412 \& STACK 1: MAGIC
413 \& CX 0: SUB =>
414 \& retop=(null)
415 \& CX 1: EVAL => *
416 \& retop=nextstate
417 .Ve
418 .PP
419 The \fBdie()\fR pops the first \f(CW\*(C`CXt_EVAL\*(C'\fR off the context stack, sets
420 \&\f(CW\*(C`PL_restartop\*(C'\fR from it, does a \f(CWJMPENV_JUMP(3)\fR, and control returns
421 to the \f(CW\*(C`JMPENV\*(C'\fR level set in \fBdocatch()\fR. This then starts another
422 third-level runops level, which executes the \f(CW\*(C`nextstate\*(C'\fR, \f(CW\*(C`pushmark\*(C'\fR and
423 \&\f(CW\*(C`die\*(C'\fR ops from line 4. At the point that the second \fBpp_die()\fR is called,
424 the C call stack looks exactly like that above, even though we are no
425 longer within an inner eval. However, the context stack now looks like
426 this, i.e. with the top CXt_EVAL popped:
427 .PP
428 .Vb 7
429 \& STACK 0: MAIN
430 \& CX 0: BLOCK =>
431 \& CX 1: EVAL => AV() PV("A"\e0)
432 \& retop=leave
433 \& STACK 1: MAGIC
434 \& CX 0: SUB =>
435 \& retop=(null)
436 .Ve
437 .PP
438 The \fBdie()\fR on line 4 pops the context stack back down to the \f(CW\*(C`CXt_EVAL\*(C'\fR,
439 leaving it as:
440 .PP
441 .Vb 2
442 \& STACK 0: MAIN
443 \& CX 0: BLOCK =>
444 .Ve
445 .PP
446 As usual, \f(CW\*(C`PL_restartop\*(C'\fR is extracted from the \f(CW\*(C`CXt_EVAL\*(C'\fR, and a
447 \&\fBJMPENV_JUMP\fR\|(3) done, which pops the C stack back to the \fBdocatch()\fR:
448 .PP
449 .Vb 9
450 \& #8 S_docatch() # JMPENV level 2
451 \& #7 Perl_pp_entertry()
452 \& #6 Perl_runops() # runops loop 2
453 \& #5 Perl_call_sv()
454 \& #4 Perl_pp_tie()
455 \& #3 Perl_runops() # runops loop 1
456 \& #2 S_run_body()
457 \& #1 perl_run() # JMPENV level 1
458 \& #0 main()
459 .Ve
460 .PP
461 In this case, because the \f(CW\*(C`JMPENV\*(C'\fR level recorded in the \f(CW\*(C`CXt_EVAL\*(C'\fR
462 differs from the current one, \fBdocatch()\fR just does a \fBJMPENV_JUMP\fR\|(3)
463 to re-throw the exception, and the C stack unwinds to:
464 .PP
465 .Vb 2
466 \& #1 perl_run() # JMPENV level 1
467 \& #0 main()
468 .Ve
469 .PP
470 Because \f(CW\*(C`PL_restartop\*(C'\fR is non-null, \fBrun_body()\fR starts a new runops
471 loop, and execution continues.
472 .SS "INTERNAL VARIABLE TYPES"
473 .IX Subsection "INTERNAL VARIABLE TYPES"
474 You should by now have had a look at perlguts, which tells you about
475 Perl's internal variable types: SVs, HVs, AVs and the rest. If not, do
476 that now.
477 .PP
478 These variables are used not only to represent Perl-space variables,
479 but also any constants in the code, as well as some structures
480 completely internal to Perl. The symbol table, for instance, is an
481 ordinary Perl hash. Your code is represented by an SV as it's read into
482 the parser; any program files you call are opened via ordinary Perl
483 filehandles, and so on.
484 .PP
485 The core Devel::Peek module lets us examine SVs from a
486 Perl program. Let's see, for instance, how Perl treats the constant
487 \&\f(CW"hello"\fR.
488 .PP
489 .Vb 7
490 \& % perl \-MDevel::Peek \-e \*(AqDump("hello")\*(Aq
491 \& 1 SV = PV(0xa041450) at 0xa04ecbc
492 \& 2 REFCNT = 1
493 \& 3 FLAGS = (POK,READONLY,pPOK)
494 \& 4 PV = 0xa0484e0 "hello"\e0
495 \& 5 CUR = 5
496 \& 6 LEN = 6
497 .Ve
498 .PP
499 Reading \f(CW\*(C`Devel::Peek\*(C'\fR output takes a bit of practise, so let's go
500 through it line by line.
501 .PP
502 Line 1 tells us we're looking at an SV which lives at \f(CW0xa04ecbc\fR in
503 memory. SVs themselves are very simple structures, but they contain a
504 pointer to a more complex structure. In this case, it's a PV, a
505 structure which holds a string value, at location \f(CW0xa041450\fR. Line 2
506 is the reference count; there are no other references to this data, so
507 it's 1.
508 .PP
509 Line 3 are the flags for this SV \- it's OK to use it as a PV, it's a
510 read-only SV (because it's a constant) and the data is a PV internally.
511 Next we've got the contents of the string, starting at location
512 \&\f(CW0xa0484e0\fR.
513 .PP
514 Line 5 gives us the current length of the string \- note that this does
515 \&\fBnot\fR include the null terminator. Line 6 is not the length of the
516 string, but the length of the currently allocated buffer; as the string
517 grows, Perl automatically extends the available storage via a routine
518 called \f(CW\*(C`SvGROW\*(C'\fR.
519 .PP
520 You can get at any of these quantities from C very easily; just add
521 \&\f(CW\*(C`Sv\*(C'\fR to the name of the field shown in the snippet, and you've got a
522 macro which will return the value: \f(CWSvCUR(sv)\fR returns the current
523 length of the string, \f(CWSvREFCOUNT(sv)\fR returns the reference count,
524 \&\f(CW\*(C`SvPV(sv, len)\*(C'\fR returns the string itself with its length, and so on.
525 More macros to manipulate these properties can be found in perlguts.
526 .PP
527 Let's take an example of manipulating a PV, from \f(CW\*(C`sv_catpvn\*(C'\fR, in
528 \&\fIsv.c\fR
529 .PP
530 .Vb 5
531 \& 1 void
532 \& 2 Perl_sv_catpvn(pTHX_ SV *sv, const char *ptr, STRLEN len)
533 \& 3 {
534 \& 4 STRLEN tlen;
535 \& 5 char *junk;
536 \&
537 \& 6 junk = SvPV_force(sv, tlen);
538 \& 7 SvGROW(sv, tlen + len + 1);
539 \& 8 if (ptr == junk)
540 \& 9 ptr = SvPVX(sv);
541 \& 10 Move(ptr,SvPVX(sv)+tlen,len,char);
542 \& 11 SvCUR(sv) += len;
543 \& 12 *SvEND(sv) = \*(Aq\e0\*(Aq;
544 \& 13 (void)SvPOK_only_UTF8(sv); /* validate pointer */
545 \& 14 SvTAINT(sv);
546 \& 15 }
547 .Ve
548 .PP
549 This is a function which adds a string, \f(CW\*(C`ptr\*(C'\fR, of length \f(CW\*(C`len\*(C'\fR onto
550 the end of the PV stored in \f(CW\*(C`sv\*(C'\fR. The first thing we do in line 6 is
551 make sure that the SV \fBhas\fR a valid PV, by calling the \f(CW\*(C`SvPV_force\*(C'\fR
552 macro to force a PV. As a side effect, \f(CW\*(C`tlen\*(C'\fR gets set to the current
553 value of the PV, and the PV itself is returned to \f(CW\*(C`junk\*(C'\fR.
554 .PP
555 In line 7, we make sure that the SV will have enough room to
556 accommodate the old string, the new string and the null terminator. If
557 \&\f(CW\*(C`LEN\*(C'\fR isn't big enough, \f(CW\*(C`SvGROW\*(C'\fR will reallocate space for us.
558 .PP
559 Now, if \f(CW\*(C`junk\*(C'\fR is the same as the string we're trying to add, we can
560 grab the string directly from the SV; \f(CW\*(C`SvPVX\*(C'\fR is the address of the PV
561 in the SV.
562 .PP
563 Line 10 does the actual catenation: the \f(CW\*(C`Move\*(C'\fR macro moves a chunk of
564 memory around: we move the string \f(CW\*(C`ptr\*(C'\fR to the end of the PV \- that's
565 the start of the PV plus its current length. We're moving \f(CW\*(C`len\*(C'\fR bytes
566 of type \f(CW\*(C`char\*(C'\fR. After doing so, we need to tell Perl we've extended
567 the string, by altering \f(CW\*(C`CUR\*(C'\fR to reflect the new length. \f(CW\*(C`SvEND\*(C'\fR is a
568 macro which gives us the end of the string, so that needs to be a
569 \&\f(CW"\e0"\fR.
570 .PP
571 Line 13 manipulates the flags; since we've changed the PV, any IV or NV
572 values will no longer be valid: if we have \f(CW\*(C`$x=10; $x.="6";\*(C'\fR we don't
573 want to use the old IV of 10. \f(CW\*(C`SvPOK_only_utf8\*(C'\fR is a special
574 UTF\-8\-aware version of \f(CW\*(C`SvPOK_only\*(C'\fR, a macro which turns off the IOK
575 and NOK flags and turns on POK. The final \f(CW\*(C`SvTAINT\*(C'\fR is a macro which
576 launders tainted data if taint mode is turned on.
577 .PP
578 AVs and HVs are more complicated, but SVs are by far the most common
579 variable type being thrown around. Having seen something of how we
580 manipulate these, let's go on and look at how the op tree is
581 constructed.
582 .SH "OP TREES"
583 .IX Header "OP TREES"
584 First, what is the op tree, anyway? The op tree is the parsed
585 representation of your program, as we saw in our section on parsing,
586 and it's the sequence of operations that Perl goes through to execute
587 your program, as we saw in "Running".
588 .PP
589 An op is a fundamental operation that Perl can perform: all the
590 built-in functions and operators are ops, and there are a series of ops
591 which deal with concepts the interpreter needs internally \- entering
592 and leaving a block, ending a statement, fetching a variable, and so
593 on.
594 .PP
595 The op tree is connected in two ways: you can imagine that there are
596 two "routes" through it, two orders in which you can traverse the tree.
597 First, parse order reflects how the parser understood the code, and
598 secondly, execution order tells perl what order to perform the
599 operations in.
600 .PP
601 The easiest way to examine the op tree is to stop Perl after it has
602 finished parsing, and get it to dump out the tree. This is exactly what
603 the compiler backends B::Terse, B::Concise
604 and CPAN module <B::Debug do.
605 .PP
606 Let's have a look at how Perl sees \f(CW\*(C`$x = $y + $z\*(C'\fR:
607 .PP
608 .Vb 12
609 \& % perl \-MO=Terse \-e \*(Aq$x=$y+$z\*(Aq
610 \& 1 LISTOP (0x8179888) leave
611 \& 2 OP (0x81798b0) enter
612 \& 3 COP (0x8179850) nextstate
613 \& 4 BINOP (0x8179828) sassign
614 \& 5 BINOP (0x8179800) add [1]
615 \& 6 UNOP (0x81796e0) null [15]
616 \& 7 SVOP (0x80fafe0) gvsv GV (0x80fa4cc) *y
617 \& 8 UNOP (0x81797e0) null [15]
618 \& 9 SVOP (0x8179700) gvsv GV (0x80efeb0) *z
619 \& 10 UNOP (0x816b4f0) null [15]
620 \& 11 SVOP (0x816dcf0) gvsv GV (0x80fa460) *x
621 .Ve
622 .PP
623 Let's start in the middle, at line 4. This is a BINOP, a binary
624 operator, which is at location \f(CW0x8179828\fR. The specific operator in
625 question is \f(CW\*(C`sassign\*(C'\fR \- scalar assignment \- and you can find the code
626 which implements it in the function \f(CW\*(C`pp_sassign\*(C'\fR in \fIpp_hot.c\fR. As a
627 binary operator, it has two children: the add operator, providing the
628 result of \f(CW\*(C`$y+$z\*(C'\fR, is uppermost on line 5, and the left hand side is
629 on line 10.
630 .PP
631 Line 10 is the null op: this does exactly nothing. What is that doing
632 there? If you see the null op, it's a sign that something has been
633 optimized away after parsing. As we mentioned in "Optimization", the
634 optimization stage sometimes converts two operations into one, for
635 example when fetching a scalar variable. When this happens, instead of
636 rewriting the op tree and cleaning up the dangling pointers, it's
637 easier just to replace the redundant operation with the null op.
638 Originally, the tree would have looked like this:
639 .PP
640 .Vb 2
641 \& 10 SVOP (0x816b4f0) rv2sv [15]
642 \& 11 SVOP (0x816dcf0) gv GV (0x80fa460) *x
643 .Ve
644 .PP
645 That is, fetch the \f(CW\*(C`a\*(C'\fR entry from the main symbol table, and then look
646 at the scalar component of it: \f(CW\*(C`gvsv\*(C'\fR (\f(CW\*(C`pp_gvsv\*(C'\fR in \fIpp_hot.c\fR)
647 happens to do both these things.
648 .PP
649 The right hand side, starting at line 5 is similar to what we've just
650 seen: we have the \f(CW\*(C`add\*(C'\fR op (\f(CW\*(C`pp_add\*(C'\fR, also in \fIpp_hot.c\fR) add
651 together two \f(CW\*(C`gvsv\*(C'\fRs.
652 .PP
653 Now, what's this about?
654 .PP
655 .Vb 3
656 \& 1 LISTOP (0x8179888) leave
657 \& 2 OP (0x81798b0) enter
658 \& 3 COP (0x8179850) nextstate
659 .Ve
660 .PP
661 \&\f(CW\*(C`enter\*(C'\fR and \f(CW\*(C`leave\*(C'\fR are scoping ops, and their job is to perform any
662 housekeeping every time you enter and leave a block: lexical variables
663 are tidied up, unreferenced variables are destroyed, and so on. Every
664 program will have those first three lines: \f(CW\*(C`leave\*(C'\fR is a list, and its
665 children are all the statements in the block. Statements are delimited
666 by \f(CW\*(C`nextstate\*(C'\fR, so a block is a collection of \f(CW\*(C`nextstate\*(C'\fR ops, with
667 the ops to be performed for each statement being the children of
668 \&\f(CW\*(C`nextstate\*(C'\fR. \f(CW\*(C`enter\*(C'\fR is a single op which functions as a marker.
669 .PP
670 That's how Perl parsed the program, from top to bottom:
671 .PP
672 .Vb 10
673 \& Program
674 \& |
675 \& Statement
676 \& |
677 \& =
678 \& / \e
679 \& / \e
680 \& $x +
681 \& / \e
682 \& $y $z
683 .Ve
684 .PP
685 However, it's impossible to \fBperform\fR the operations in this order:
686 you have to find the values of \f(CW$y\fR and \f(CW$z\fR before you add them
687 together, for instance. So, the other thread that runs through the op
688 tree is the execution order: each op has a field \f(CW\*(C`op_next\*(C'\fR which
689 points to the next op to be run, so following these pointers tells us
690 how perl executes the code. We can traverse the tree in this order
691 using the \f(CW\*(C`exec\*(C'\fR option to \f(CW\*(C`B::Terse\*(C'\fR:
692 .PP
693 .Vb 9
694 \& % perl \-MO=Terse,exec \-e \*(Aq$x=$y+$z\*(Aq
695 \& 1 OP (0x8179928) enter
696 \& 2 COP (0x81798c8) nextstate
697 \& 3 SVOP (0x81796c8) gvsv GV (0x80fa4d4) *y
698 \& 4 SVOP (0x8179798) gvsv GV (0x80efeb0) *z
699 \& 5 BINOP (0x8179878) add [1]
700 \& 6 SVOP (0x816dd38) gvsv GV (0x80fa468) *x
701 \& 7 BINOP (0x81798a0) sassign
702 \& 8 LISTOP (0x8179900) leave
703 .Ve
704 .PP
705 This probably makes more sense for a human: enter a block, start a
706 statement. Get the values of \f(CW$y\fR and \f(CW$z\fR, and add them together.
707 Find \f(CW$x\fR, and assign one to the other. Then leave.
708 .PP
709 The way Perl builds up these op trees in the parsing process can be
710 unravelled by examining \fItoke.c\fR, the lexer, and \fIperly.y\fR, the YACC
711 grammar. Let's look at the code that constructs the tree for \f(CW$x = $y +
712 $z\fR.
713 .PP
714 First, we'll look at the \f(CW\*(C`Perl_yylex\*(C'\fR function in the lexer. We want to
715 look for \f(CW\*(C`case \*(Aqx\*(Aq\*(C'\fR, where x is the first character of the operator.
716 (Incidentally, when looking for the code that handles a keyword, you'll
717 want to search for \f(CW\*(C`KEY_foo\*(C'\fR where "foo" is the keyword.) Here is the code
718 that handles assignment (there are quite a few operators beginning with
719 \&\f(CW\*(C`=\*(C'\fR, so most of it is omitted for brevity):
720 .PP
721 .Vb 5
722 \& 1 case \*(Aq=\*(Aq:
723 \& 2 s++;
724 \& ... code that handles == => etc. and pod ...
725 \& 3 pl_yylval.ival = 0;
726 \& 4 OPERATOR(ASSIGNOP);
727 .Ve
728 .PP
729 We can see on line 4 that our token type is \f(CW\*(C`ASSIGNOP\*(C'\fR (\f(CW\*(C`OPERATOR\*(C'\fR is a
730 macro, defined in \fItoke.c\fR, that returns the token type, among other
731 things). And \f(CW\*(C`+\*(C'\fR:
732 .PP
733 .Vb 10
734 \& 1 case \*(Aq+\*(Aq:
735 \& 2 {
736 \& 3 const char tmp = *s++;
737 \& ... code for ++ ...
738 \& 4 if (PL_expect == XOPERATOR) {
739 \& ...
740 \& 5 Aop(OP_ADD);
741 \& 6 }
742 \& ...
743 \& 7 }
744 .Ve
745 .PP
746 Line 4 checks what type of token we are expecting. \f(CW\*(C`Aop\*(C'\fR returns a token.
747 If you search for \f(CW\*(C`Aop\*(C'\fR elsewhere in \fItoke.c\fR, you will see that it
748 returns an \f(CW\*(C`ADDOP\*(C'\fR token.
749 .PP
750 Now that we know the two token types we want to look for in the parser,
751 let's take the piece of \fIperly.y\fR we need to construct the tree for
752 \&\f(CW\*(C`$x = $y + $z\*(C'\fR
753 .PP
754 .Vb 4
755 \& 1 term : term ASSIGNOP term
756 \& 2 { $$ = newASSIGNOP(OPf_STACKED, $1, $2, $3); }
757 \& 3 | term ADDOP term
758 \& 4 { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
759 .Ve
760 .PP
761 If you're not used to reading BNF grammars, this is how it works:
762 You're fed certain things by the tokeniser, which generally end up in
763 upper case. \f(CW\*(C`ADDOP\*(C'\fR and \f(CW\*(C`ASSIGNOP\*(C'\fR are examples of "terminal symbols",
764 because you can't get any simpler than
765 them.
766 .PP
767 The grammar, lines one and three of the snippet above, tells you how to
768 build up more complex forms. These complex forms, "non-terminal
769 symbols" are generally placed in lower case. \f(CW\*(C`term\*(C'\fR here is a
770 non-terminal symbol, representing a single expression.
771 .PP
772 The grammar gives you the following rule: you can make the thing on the
773 left of the colon if you see all the things on the right in sequence.
774 This is called a "reduction", and the aim of parsing is to completely
775 reduce the input. There are several different ways you can perform a
776 reduction, separated by vertical bars: so, \f(CW\*(C`term\*(C'\fR followed by \f(CW\*(C`=\*(C'\fR
777 followed by \f(CW\*(C`term\*(C'\fR makes a \f(CW\*(C`term\*(C'\fR, and \f(CW\*(C`term\*(C'\fR followed by \f(CW\*(C`+\*(C'\fR
778 followed by \f(CW\*(C`term\*(C'\fR can also make a \f(CW\*(C`term\*(C'\fR.
779 .PP
780 So, if you see two terms with an \f(CW\*(C`=\*(C'\fR or \f(CW\*(C`+\*(C'\fR, between them, you can
781 turn them into a single expression. When you do this, you execute the
782 code in the block on the next line: if you see \f(CW\*(C`=\*(C'\fR, you'll do the code
783 in line 2. If you see \f(CW\*(C`+\*(C'\fR, you'll do the code in line 4. It's this
784 code which contributes to the op tree.
785 .PP
786 .Vb 2
787 \& | term ADDOP term
788 \& { $$ = newBINOP($2, 0, scalar($1), scalar($3)); }
789 .Ve
790 .PP
791 What this does is creates a new binary op, and feeds it a number of
792 variables. The variables refer to the tokens: \f(CW$1\fR is the first token
793 in the input, \f(CW$2\fR the second, and so on \- think regular expression
794 backreferences. \f(CW$$\fR is the op returned from this reduction. So, we
795 call \f(CW\*(C`newBINOP\*(C'\fR to create a new binary operator. The first parameter
796 to \f(CW\*(C`newBINOP\*(C'\fR, a function in \fIop.c\fR, is the op type. It's an addition
797 operator, so we want the type to be \f(CW\*(C`ADDOP\*(C'\fR. We could specify this
798 directly, but it's right there as the second token in the input, so we
799 use \f(CW$2\fR. The second parameter is the op's flags: 0 means "nothing
800 special". Then the things to add: the left and right hand side of our
801 expression, in scalar context.
802 .PP
803 The functions that create ops, which have names like \f(CW\*(C`newUNOP\*(C'\fR and
804 \&\f(CW\*(C`newBINOP\*(C'\fR, call a "check" function associated with each op type, before
805 returning the op. The check functions can mangle the op as they see fit,
806 and even replace it with an entirely new one. These functions are defined
807 in \fIop.c\fR, and have a \f(CW\*(C`Perl_ck_\*(C'\fR prefix. You can find out which
808 check function is used for a particular op type by looking in
809 \&\fIregen/opcodes\fR. Take \f(CW\*(C`OP_ADD\*(C'\fR, for example. (\f(CW\*(C`OP_ADD\*(C'\fR is the token
810 value from the \f(CWAop(OP_ADD)\fR in \fItoke.c\fR which the parser passes to
811 \&\f(CW\*(C`newBINOP\*(C'\fR as its first argument.) Here is the relevant line:
812 .PP
813 .Vb 1
814 \& add addition (+) ck_null IfsT2 S S
815 .Ve
816 .PP
817 The check function in this case is \f(CW\*(C`Perl_ck_null\*(C'\fR, which does nothing.
818 Let's look at a more interesting case:
819 .PP
820 .Vb 1
821 \& readline <HANDLE> ck_readline t% F?
822 .Ve
823 .PP
824 And here is the function from \fIop.c\fR:
825 .PP
826 .Vb 10
827 \& 1 OP *
828 \& 2 Perl_ck_readline(pTHX_ OP *o)
829 \& 3 {
830 \& 4 PERL_ARGS_ASSERT_CK_READLINE;
831 \& 5
832 \& 6 if (o\->op_flags & OPf_KIDS) {
833 \& 7 OP *kid = cLISTOPo\->op_first;
834 \& 8 if (kid\->op_type == OP_RV2GV)
835 \& 9 kid\->op_private |= OPpALLOW_FAKE;
836 \& 10 }
837 \& 11 else {
838 \& 12 OP * const newop
839 \& 13 = newUNOP(OP_READLINE, 0, newGVOP(OP_GV, 0,
840 \& 14 PL_argvgv));
841 \& 15 op_free(o);
842 \& 16 return newop;
843 \& 17 }
844 \& 18 return o;
845 \& 19 }
846 .Ve
847 .PP
848 One particularly interesting aspect is that if the op has no kids (i.e.,
849 \&\f(CWreadline()\fR or \f(CW\*(C`<>\*(C'\fR) the op is freed and replaced with an entirely
850 new one that references \f(CW*ARGV\fR (lines 12\-16).
851 .SH STACKS
852 .IX Header "STACKS"
853 When perl executes something like \f(CW\*(C`addop\*(C'\fR, how does it pass on its
854 results to the next op? The answer is, through the use of stacks. Perl
855 has a number of stacks to store things it's currently working on, and
856 we'll look at the three most important ones here.
857 .SS "Argument stack"
858 .IX Subsection "Argument stack"
859 Arguments are passed to PP code and returned from PP code using the
860 argument stack, \f(CW\*(C`ST\*(C'\fR. The typical way to handle arguments is to pop
861 them off the stack, deal with them how you wish, and then push the
862 result back onto the stack. This is how, for instance, the cosine
863 operator works:
864 .PP
865 .Vb 4
866 \& NV value;
867 \& value = POPn;
868 \& value = Perl_cos(value);
869 \& XPUSHn(value);
870 .Ve
871 .PP
872 We'll see a more tricky example of this when we consider Perl's macros
873 below. \f(CW\*(C`POPn\*(C'\fR gives you the NV (floating point value) of the top SV on
874 the stack: the \f(CW$x\fR in \f(CWcos($x)\fR. Then we compute the cosine, and
875 push the result back as an NV. The \f(CW\*(C`X\*(C'\fR in \f(CW\*(C`XPUSHn\*(C'\fR means that the
876 stack should be extended if necessary \- it can't be necessary here,
877 because we know there's room for one more item on the stack, since
878 we've just removed one! The \f(CW\*(C`XPUSH*\*(C'\fR macros at least guarantee safety.
879 .PP
880 Alternatively, you can fiddle with the stack directly: \f(CW\*(C`SP\*(C'\fR gives you
881 the first element in your portion of the stack, and \f(CW\*(C`TOP*\*(C'\fR gives you
882 the top SV/IV/NV/etc. on the stack. So, for instance, to do unary
883 negation of an integer:
884 .PP
885 .Vb 1
886 \& SETi(\-TOPi);
887 .Ve
888 .PP
889 Just set the integer value of the top stack entry to its negation.
890 .PP
891 Argument stack manipulation in the core is exactly the same as it is in
892 XSUBs \- see perlxstut, perlxs and perlguts for a longer
893 description of the macros used in stack manipulation.
894 .SS "Mark stack"
895 .IX Subsection "Mark stack"
896 I say "your portion of the stack" above because PP code doesn't
897 necessarily get the whole stack to itself: if your function calls
898 another function, you'll only want to expose the arguments aimed for
899 the called function, and not (necessarily) let it get at your own data.
900 The way we do this is to have a "virtual" bottom-of-stack, exposed to
901 each function. The mark stack keeps bookmarks to locations in the
902 argument stack usable by each function. For instance, when dealing with
903 a tied variable, (internally, something with "P" magic) Perl has to
904 call methods for accesses to the tied variables. However, we need to
905 separate the arguments exposed to the method to the argument exposed to
906 the original function \- the store or fetch or whatever it may be.
907 Here's roughly how the tied \f(CW\*(C`push\*(C'\fR is implemented; see \f(CW\*(C`av_push\*(C'\fR in
908 \&\fIav.c\fR:
909 .PP
910 .Vb 8
911 \& 1 PUSHMARK(SP);
912 \& 2 EXTEND(SP,2);
913 \& 3 PUSHs(SvTIED_obj((SV*)av, mg));
914 \& 4 PUSHs(val);
915 \& 5 PUTBACK;
916 \& 6 ENTER;
917 \& 7 call_method("PUSH", G_SCALAR|G_DISCARD);
918 \& 8 LEAVE;
919 .Ve
920 .PP
921 Let's examine the whole implementation, for practice:
922 .PP
923 .Vb 1
924 \& 1 PUSHMARK(SP);
925 .Ve
926 .PP
927 Push the current state of the stack pointer onto the mark stack. This
928 is so that when we've finished adding items to the argument stack, Perl
929 knows how many things we've added recently.
930 .PP
931 .Vb 3
932 \& 2 EXTEND(SP,2);
933 \& 3 PUSHs(SvTIED_obj((SV*)av, mg));
934 \& 4 PUSHs(val);
935 .Ve
936 .PP
937 We're going to add two more items onto the argument stack: when you
938 have a tied array, the \f(CW\*(C`PUSH\*(C'\fR subroutine receives the object and the
939 value to be pushed, and that's exactly what we have here \- the tied
940 object, retrieved with \f(CW\*(C`SvTIED_obj\*(C'\fR, and the value, the SV \f(CW\*(C`val\*(C'\fR.
941 .PP
942 .Vb 1
943 \& 5 PUTBACK;
944 .Ve
945 .PP
946 Next we tell Perl to update the global stack pointer from our internal
947 variable: \f(CW\*(C`dSP\*(C'\fR only gave us a local copy, not a reference to the
948 global.
949 .PP
950 .Vb 3
951 \& 6 ENTER;
952 \& 7 call_method("PUSH", G_SCALAR|G_DISCARD);
953 \& 8 LEAVE;
954 .Ve
955 .PP
956 \&\f(CW\*(C`ENTER\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR localise a block of code \- they make sure that
957 all variables are tidied up, everything that has been localised gets
958 its previous value returned, and so on. Think of them as the \f(CW\*(C`{\*(C'\fR and
959 \&\f(CW\*(C`}\*(C'\fR of a Perl block.
960 .PP
961 To actually do the magic method call, we have to call a subroutine in
962 Perl space: \f(CW\*(C`call_method\*(C'\fR takes care of that, and it's described in
963 perlcall. We call the \f(CW\*(C`PUSH\*(C'\fR method in scalar context, and we're
964 going to discard its return value. The \fBcall_method()\fR function removes
965 the top element of the mark stack, so there is nothing for the caller
966 to clean up.
967 .SS "Save stack"
968 .IX Subsection "Save stack"
969 C doesn't have a concept of local scope, so perl provides one. We've
970 seen that \f(CW\*(C`ENTER\*(C'\fR and \f(CW\*(C`LEAVE\*(C'\fR are used as scoping braces; the save
971 stack implements the C equivalent of, for example:
972 .PP
973 .Vb 4
974 \& {
975 \& local $foo = 42;
976 \& ...
977 \& }
978 .Ve
979 .PP
980 See "Localizing changes" in perlguts for how to use the save stack.
981 .SH "MILLIONS OF MACROS"
982 .IX Header "MILLIONS OF MACROS"
983 One thing you'll notice about the Perl source is that it's full of
984 macros. Some have called the pervasive use of macros the hardest thing
985 to understand, others find it adds to clarity. Let's take an example,
986 a stripped-down version the code which implements the addition operator:
987 .PP
988 .Vb 10
989 \& 1 PP(pp_add)
990 \& 2 {
991 \& 3 dSP; dATARGET;
992 \& 4 tryAMAGICbin_MG(add_amg, AMGf_assign|AMGf_numeric);
993 \& 5 {
994 \& 6 dPOPTOPnnrl_ul;
995 \& 7 SETn( left + right );
996 \& 8 RETURN;
997 \& 9 }
998 \& 10 }
999 .Ve
1000 .PP
1001 Every line here (apart from the braces, of course) contains a macro.
1002 The first line sets up the function declaration as Perl expects for PP
1003 code; line 3 sets up variable declarations for the argument stack and
1004 the target, the return value of the operation. Line 4 tries to see
1005 if the addition operation is overloaded; if so, the appropriate
1006 subroutine is called.
1007 .PP
1008 Line 6 is another variable declaration \- all variable declarations
1009 start with \f(CW\*(C`d\*(C'\fR \- which pops from the top of the argument stack two NVs
1010 (hence \f(CW\*(C`nn\*(C'\fR) and puts them into the variables \f(CW\*(C`right\*(C'\fR and \f(CW\*(C`left\*(C'\fR,
1011 hence the \f(CW\*(C`rl\*(C'\fR. These are the two operands to the addition operator.
1012 Next, we call \f(CW\*(C`SETn\*(C'\fR to set the NV of the return value to the result
1013 of adding the two values. This done, we return \- the \f(CW\*(C`RETURN\*(C'\fR macro
1014 makes sure that our return value is properly handled, and we pass the
1015 next operator to run back to the main run loop.
1016 .PP
1017 Most of these macros are explained in perlapi, and some of the more
1018 important ones are explained in perlxs as well. Pay special
1019 attention to "Background and MULTIPLICITY" in perlguts for
1020 information on the \f(CW\*(C`[pad]THX_?\*(C'\fR macros.
1021 .SH "FURTHER READING"
1022 .IX Header "FURTHER READING"
1023 For more information on the Perl internals, please see the documents
1024 listed at "Internals and C Language Interface" in perl.