This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Proper fix for CvOUTSIDE weak refcounting
[perl5.git] / pod / perlintern.pod
CommitLineData
954c1994
GS
1=head1 NAME
2
1c846c1f 3perlintern - autogenerated documentation of purely B<internal>
954c1994
GS
4 Perl functions
5
6=head1 DESCRIPTION
7
1c846c1f 8This file is the autogenerated documentation of functions in the
4375e838 9Perl interpreter that are documented using Perl's internal documentation
1c846c1f 10format but are not marked as part of the Perl API. In other words,
954c1994
GS
11B<they are not for use in extensions>!
12
a8586c98 13
7dafbf52
DM
14=head1 CV reference counts and CvOUTSIDE
15
16=over 8
17
18=item CvWEAKOUTSIDE
19
20Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
21CV (if any). Because pointers to anonymous sub prototypes are
22stored in C<&> pad slots, it is a possible to get a circular reference,
23with the parent pointing to the child and vice-versa. To avoid the
24ensuing memory leak, we do not increment the reference count of the CV
25pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
26has a C<&> pad slot pointing back to us. In this case, we set the
27C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
28circumstances we should decrement the refcount of the parent when freeing
29the child.
30
31There is a further complication with non-closure anonymous subs (ie those
32that do not refer to any lexicals outside that sub). In this case, the
33anonymous prototype is shared rather than being cloned. This has the
34consequence that the parent may be freed while there are still active
35children, eg
36
37 BEGIN { $a = sub { eval '$x' } }
38
39In this case, the BEGIN is freed immediately after execution since there
40are no active references to it: the anon sub prototype has
41C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
42CV, so it doesn't contribute to BEGIN's refcount either. When $a is
43executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
44and the freed BEGIN is accessed.
45
46To avoid this, whenever a CV and its associated pad is freed, any
47C<&> entries in the pad are explicitly removed from the pad, and if the
48refcount of the pointed-to anon sub is still positive, then that
49child's C<CvOUTSIDE> is set to point to its grandparent. This will only
50occur in the single specific case of a non-closure anon prototype
51having one or more active references (such as C<$a> above).
52
53One other thing to consider is that a CV may be merely undefined
54rather than freed, eg C<undef &foo>. In this case, its refcount may
55not have reached zero, but we still delete its pad and its C<CvROOT> etc.
56Since various children may still have their C<CvOUTSIDE> pointing at this
57undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
58the chain of lexical scopes is unbroken. For example, the following
59should print 123:
60
61 my $x = 123;
62 sub tmp { sub { eval '$x' } }
63 my $a = tmp();
64 undef &tmp;
65 print $a->();
66
67 bool CvWEAKOUTSIDE(CV *cv)
68
69=for hackers
70Found in file cv.h
71
72
73=back
74
dd2155a4
DM
75=head1 Functions in file pad.h
76
77
78=over 8
79
80=item CX_CURPAD_SAVE
81
82Save the current pad in the given context block structure.
83
84 void CX_CURPAD_SAVE(struct context)
85
86=for hackers
87Found in file pad.h
88
89=item CX_CURPAD_SV
90
91Access the SV at offset po in the saved current pad in the given
92context block structure (can be used as an lvalue).
93
f3548bdc 94 SV * CX_CURPAD_SV(struct context, PADOFFSET po)
dd2155a4
DM
95
96=for hackers
97Found in file pad.h
98
99=item PAD_BASE_SV
100
101Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
102
103 SV * PAD_BASE_SV (PADLIST padlist, PADOFFSET po)
104
105=for hackers
106Found in file pad.h
107
108=item PAD_CLONE_VARS
109
110|CLONE_PARAMS* param
111Clone the state variables associated with running and compiling pads.
112
113 void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
114
115=for hackers
116Found in file pad.h
117
118=item PAD_COMPNAME_FLAGS
119
120Return the flags for the current compiling pad name
121at offset C<po>. Assumes a valid slot entry.
122
123 U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
124
125=for hackers
126Found in file pad.h
127
128=item PAD_COMPNAME_GEN
129
130The generation number of the name at offset C<po> in the current
131compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose.
132
133 STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
134
135=for hackers
136Found in file pad.h
137
138=item PAD_COMPNAME_OURSTASH
139
140Return the stash associated with an C<our> variable.
141Assumes the slot entry is a valid C<our> lexical.
142
143 HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
144
145=for hackers
146Found in file pad.h
147
148=item PAD_COMPNAME_PV
149
150Return the name of the current compiling pad name
151at offset C<po>. Assumes a valid slot entry.
152
153 char * PAD_COMPNAME_PV(PADOFFSET po)
154
155=for hackers
156Found in file pad.h
157
158=item PAD_COMPNAME_TYPE
159
160Return the type (stash) of the current compiling pad name at offset
161C<po>. Must be a valid name. Returns null if not typed.
162
163 HV * PAD_COMPNAME_TYPE(PADOFFSET po)
164
165=for hackers
166Found in file pad.h
167
168=item PAD_DUP
169
170Clone a padlist.
171
172 void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
173
174=for hackers
175Found in file pad.h
176
f3548bdc
DM
177=item PAD_RESTORE_LOCAL
178
179Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
180
181 void PAD_RESTORE_LOCAL(PAD *opad)
182
183=for hackers
184Found in file pad.h
185
186=item PAD_SAVE_LOCAL
187
188Save the current pad to the local variable opad, then make the
189current pad equal to npad
190
191 void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
192
193=for hackers
194Found in file pad.h
195
dd2155a4
DM
196=item PAD_SAVE_SETNULLPAD
197
198Save the current pad then set it to null.
199
200 void PAD_SAVE_SETNULLPAD()
201
202=for hackers
203Found in file pad.h
204
205=item PAD_SETSV
206
207Set the slot at offset C<po> in the current pad to C<sv>
208
209 SV * PAD_SETSV (PADOFFSET po, SV* sv)
210
211=for hackers
212Found in file pad.h
213
214=item PAD_SET_CUR
215
216Set the current pad to be pad C<n> in the padlist, saving
217the previous current pad.
218
219 void PAD_SET_CUR (PADLIST padlist, I32 n)
220
221=for hackers
222Found in file pad.h
223
224=item PAD_SV
225
226Get the value at offset C<po> in the current pad
227
228 void PAD_SV (PADOFFSET po)
229
230=for hackers
231Found in file pad.h
232
233=item PAD_SVl
234
235Lightweight and lvalue version of C<PAD_SV>.
236Get or set the value at offset C<po> in the current pad.
237Unlike C<PAD_SV>, does not print diagnostics with -DX.
238For internal use only.
239
240 SV * PAD_SVl (PADOFFSET po)
241
242=for hackers
243Found in file pad.h
244
dd2155a4
DM
245=item SAVECLEARSV
246
247Clear the pointed to pad value on scope exit. (ie the runtime action of 'my')
248
249 void SAVECLEARSV (SV **svp)
250
251=for hackers
252Found in file pad.h
253
254=item SAVECOMPPAD
255
256save PL_comppad and PL_curpad
257
dd2155a4 258
dd2155a4
DM
259
260
261
f3548bdc 262 void SAVECOMPPAD()
dd2155a4
DM
263
264=for hackers
265Found in file pad.h
266
267=item SAVEPADSV
268
269Save a pad slot (used to restore after an iteration)
270
f3548bdc 271XXX DAPM it would make more sense to make the arg a PADOFFSET
dd2155a4
DM
272 void SAVEPADSV (PADOFFSET po)
273
274=for hackers
275Found in file pad.h
276
277
278=back
279
a3985cdc
DM
280=head1 Functions in file pp_ctl.c
281
282
283=over 8
284
285=item find_runcv
286
287Locate the CV corresponding to the currently executing sub or eval.
288
289 CV* find_runcv()
290
291=for hackers
292Found in file pp_ctl.c
293
294
295=back
296
a4f1a029 297=head1 Global Variables
78f9721b 298
a4f1a029 299=over 8
78f9721b 300
2eb25c99
JH
301=item PL_DBsingle
302
303When Perl is run in debugging mode, with the B<-d> switch, this SV is a
304boolean which indicates whether subs are being single-stepped.
305Single-stepping is automatically turned on after every step. This is the C
306variable which corresponds to Perl's $DB::single variable. See
307C<PL_DBsub>.
308
309 SV * PL_DBsingle
310
311=for hackers
312Found in file intrpvar.h
313
314=item PL_DBsub
315
316When Perl is run in debugging mode, with the B<-d> switch, this GV contains
317the SV which holds the name of the sub being debugged. This is the C
318variable which corresponds to Perl's $DB::sub variable. See
319C<PL_DBsingle>.
320
321 GV * PL_DBsub
322
323=for hackers
324Found in file intrpvar.h
325
326=item PL_DBtrace
327
328Trace variable used when Perl is run in debugging mode, with the B<-d>
329switch. This is the C variable which corresponds to Perl's $DB::trace
330variable. See C<PL_DBsingle>.
331
332 SV * PL_DBtrace
333
334=for hackers
335Found in file intrpvar.h
336
337=item PL_dowarn
338
339The C variable which corresponds to Perl's $^W warning variable.
340
341 bool PL_dowarn
342
343=for hackers
344Found in file intrpvar.h
345
346=item PL_last_in_gv
347
348The GV which was last used for a filehandle input operation. (C<< <FH> >>)
349
350 GV* PL_last_in_gv
351
352=for hackers
353Found in file thrdvar.h
354
355=item PL_ofs_sv
356
357The output field separator - C<$,> in Perl space.
358
359 SV* PL_ofs_sv
360
361=for hackers
362Found in file thrdvar.h
363
364=item PL_rs
365
366The input record separator - C<$/> in Perl space.
367
368 SV* PL_rs
369
370=for hackers
371Found in file thrdvar.h
372
645c22ef 373
a4f1a029 374=back
645c22ef 375
a4f1a029
NIS
376=head1 GV Functions
377
378=over 8
379
380=item is_gv_magical
381
382Returns C<TRUE> if given the name of a magical GV.
383
384Currently only useful internally when determining if a GV should be
385created even in rvalue contexts.
386
387C<flags> is not used at present but available for future extension to
388allow selecting particular classes of magical variable.
389
390 bool is_gv_magical(char *name, STRLEN len, U32 flags)
645c22ef
DM
391
392=for hackers
a4f1a029
NIS
393Found in file gv.c
394
395
396=back
397
398=head1 IO Functions
399
400=over 8
645c22ef 401
a8586c98
JH
402=item start_glob
403
404Function called by C<do_readline> to spawn a glob (or do the glob inside
405perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
bd16a5f0 406this glob starter is only used by miniperl during the build process.
a8586c98
JH
407Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
408
409 PerlIO* start_glob(SV* pattern, IO *io)
410
411=for hackers
412Found in file doio.c
413
a4f1a029
NIS
414
415=back
416
417=head1 Pad Data Structures
418
419=over 8
420
421=item CvPADLIST
422
423CV's can have CvPADLIST(cv) set to point to an AV.
424
425For these purposes "forms" are a kind-of CV, eval""s are too (except they're
426not callable at will and are always thrown away after the eval"" is done
427executing).
428
429XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
430but that is really the callers pad (a slot of which is allocated by
431every entersub).
432
433The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
f3548bdc 434is managed "manual" (mostly in pad.c) rather than normal av.c rules.
a4f1a029
NIS
435The items in the AV are not SVs as for a normal AV, but other AVs:
436
4370'th Entry of the CvPADLIST is an AV which represents the "names" or rather
438the "static type information" for lexicals.
439
440The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
441depth of recursion into the CV.
442The 0'th slot of a frame AV is an AV which is @_.
443other entries are storage for variables and op targets.
444
445During compilation:
446C<PL_comppad_name> is set the the the names AV.
447C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
448C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
449
f3548bdc
DM
450During execution, C<PL_comppad> and C<PL_curpad> refer to the live
451frame of the currently executing sub.
452
453Iterating over the names AV iterates over all possible pad
a4f1a029
NIS
454items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
455&PL_sv_undef "names" (see pad_alloc()).
456
457Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
458The rest are op targets/GVs/constants which are statically allocated
459or resolved at compile time. These don't have names by which they
460can be looked up from Perl code at run time through eval"" like
461my/our variables can be. Since they can't be looked up by "name"
462but only by their index allocated at compile time (which is usually
463in PL_op->op_targ), wasting a name SV for them doesn't make sense.
464
465The SVs in the names AV have their PV being the name of the variable.
dd2155a4
DM
466NV+1..IV inclusive is a range of cop_seq numbers for which the name is
467valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the
468type. For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the
469stash of the associated global (so that duplicate C<our> delarations in the
470same package can be detected). SvCUR is sometimes hijacked to
471store the generation number during compilation.
a4f1a029
NIS
472
473If SvFAKE is set on the name SV then slot in the frame AVs are
d90a703e
JH
474a REFCNT'ed references to a lexical from "outside". In this case,
475the name SV does not have a cop_seq range, since it is in scope
476throughout.
a4f1a029
NIS
477
478If the 'name' is '&' the the corresponding entry in frame AV
479is a CV representing a possible closure.
480(SvFAKE and name of '&' is not a meaningful combination currently but could
481become so if C<my sub foo {}> is implemented.)
482
483 AV * CvPADLIST(CV *cv)
484
485=for hackers
dd2155a4
DM
486Found in file pad.c
487
488=item cv_clone
489
490Clone a CV: make a new CV which points to the same code etc, but which
ad63d80f 491has a newly-created pad built by copying the prototype pad and capturing
dd2155a4
DM
492any outer lexicals.
493
494 CV* cv_clone(CV* proto)
495
496=for hackers
497Found in file pad.c
498
499=item cv_dump
500
501dump the contents of a CV
502
503 void cv_dump(CV *cv, char *title)
504
505=for hackers
506Found in file pad.c
507
508=item do_dump_pad
509
510Dump the contents of a padlist
511
512 void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
513
514=for hackers
515Found in file pad.c
516
517=item intro_my
518
519"Introduce" my variables to visible status.
520
521 U32 intro_my()
522
523=for hackers
524Found in file pad.c
525
526=item pad_add_anon
527
528Add an anon code entry to the current compiling pad
529
530 PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
531
532=for hackers
533Found in file pad.c
534
535=item pad_add_name
536
537Create a new name in the current pad at the specified offset.
538If C<typestash> is valid, the name is for a typed lexical; set the
539name's stash to that value.
540If C<ourstash> is valid, it's an our lexical, set the name's
541GvSTASH to that value
542
543Also, if the name is @.. or %.., create a new array or hash for that slot
544
545If fake, it means we're cloning an existing entry
546
547 PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone)
548
549=for hackers
550Found in file pad.c
551
552=item pad_alloc
553
554Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
555the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
556for a slot which has no name and and no active value.
557
558 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
559
560=for hackers
561Found in file pad.c
562
563=item pad_block_start
564
565Update the pad compilation state variables on entry to a new block
566
567 void pad_block_start(int full)
568
569=for hackers
570Found in file pad.c
571
572=item pad_check_dup
573
574Check for duplicate declarations: report any of:
575 * a my in the current scope with the same name;
576 * an our (anywhere in the pad) with the same name and the same stash
577 as C<ourstash>
578C<is_our> indicates that the name to check is an 'our' declaration
579
dd2155a4
DM
580 void pad_check_dup(char* name, bool is_our, HV* ourstash)
581
582=for hackers
583Found in file pad.c
584
585=item pad_findlex
586
587Find a named lexical anywhere in a chain of nested pads. Add fake entries
a3985cdc
DM
588in the inner pads if it's found in an outer one. innercv is the CV *inside*
589the chain of outer CVs to be searched. If newoff is non-null, this is a
590run-time cloning: don't add fake entries, just find the lexical and add a
591ref to it at newoff in the current pad.
dd2155a4 592
a3985cdc 593 PADOFFSET pad_findlex(char* name, PADOFFSET newoff, CV* innercv)
dd2155a4
DM
594
595=for hackers
596Found in file pad.c
597
598=item pad_findmy
599
ad63d80f 600Given a lexical name, try to find its offset, first in the current pad,
dd2155a4 601or failing that, in the pads of any lexically enclosing subs (including
ad63d80f
JP
602the complications introduced by eval). If the name is found in an outer pad,
603then a fake entry is added to the current pad.
dd2155a4
DM
604Returns the offset in the current pad, or NOT_IN_PAD on failure.
605
606 PADOFFSET pad_findmy(char* name)
607
608=for hackers
609Found in file pad.c
610
611=item pad_fixup_inner_anons
612
613For any anon CVs in the pad, change CvOUTSIDE of that CV from
7dafbf52
DM
614old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
615moved to a pre-existing CV struct.
dd2155a4
DM
616
617 void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
618
619=for hackers
620Found in file pad.c
621
622=item pad_free
623
624Free the SV at offet po in the current pad.
625
626 void pad_free(PADOFFSET po)
627
628=for hackers
629Found in file pad.c
630
631=item pad_leavemy
632
633Cleanup at end of scope during compilation: set the max seq number for
634lexicals in this scope and warn of any lexicals that never got introduced.
635
636 void pad_leavemy()
637
638=for hackers
639Found in file pad.c
640
641=item pad_new
642
ad63d80f 643Create a new compiling padlist, saving and updating the various global
dd2155a4
DM
644vars at the same time as creating the pad itself. The following flags
645can be OR'ed together:
646
647 padnew_CLONE this pad is for a cloned CV
648 padnew_SAVE save old globals
649 padnew_SAVESUB also save extra stuff for start of sub
650
651 PADLIST* pad_new(padnew_flags flags)
652
653=for hackers
654Found in file pad.c
655
656=item pad_push
657
658Push a new pad frame onto the padlist, unless there's already a pad at
659this depth, in which case don't bother creating a new one.
660If has_args is true, give the new pad an @_ in slot zero.
661
662 void pad_push(PADLIST *padlist, int depth, int has_args)
663
664=for hackers
665Found in file pad.c
666
667=item pad_reset
668
669Mark all the current temporaries for reuse
670
671 void pad_reset()
672
673=for hackers
674Found in file pad.c
675
676=item pad_setsv
677
678Set the entry at offset po in the current pad to sv.
679Use the macro PAD_SETSV() rather than calling this function directly.
680
681 void pad_setsv(PADOFFSET po, SV* sv)
682
683=for hackers
684Found in file pad.c
685
686=item pad_swipe
687
688Abandon the tmp in the current pad at offset po and replace with a
689new one.
690
691 void pad_swipe(PADOFFSET po, bool refadjust)
692
693=for hackers
694Found in file pad.c
695
696=item pad_tidy
697
698Tidy up a pad after we've finished compiling it:
699 * remove most stuff from the pads of anonsub prototypes;
700 * give it a @_;
701 * mark tmps as such.
702
703 void pad_tidy(padtidy_type type)
704
705=for hackers
706Found in file pad.c
707
708=item pad_undef
709
710Free the padlist associated with a CV.
711If parts of it happen to be current, we null the relevant
712PL_*pad* global vars so that we don't have any dangling references left.
713We also repoint the CvOUTSIDE of any about-to-be-orphaned
a3985cdc 714inner subs to the outer of this cv.
dd2155a4 715
7dafbf52
DM
716(This function should really be called pad_free, but the name was already
717taken)
718
a3985cdc 719 void pad_undef(CV* cv)
dd2155a4
DM
720
721=for hackers
722Found in file pad.c
a4f1a029
NIS
723
724
725=back
726
727=head1 Stack Manipulation Macros
728
729=over 8
730
731=item djSP
732
733Declare Just C<SP>. This is actually identical to C<dSP>, and declares
734a local copy of perl's stack pointer, available via the C<SP> macro.
735See C<SP>. (Available for backward source code compatibility with the
736old (Perl 5.005) thread model.)
737
738 djSP;
739
740=for hackers
741Found in file pp.h
742
743=item LVRET
744
745True if this op will be the return value of an lvalue subroutine
746
747=for hackers
748Found in file pp.h
749
750
751=back
752
753=head1 SV Manipulation Functions
754
755=over 8
756
757=item report_uninit
758
759Print appropriate "Use of uninitialized variable" warning
760
761 void report_uninit()
762
763=for hackers
764Found in file sv.c
765
645c22ef
DM
766=item sv_add_arena
767
768Given a chunk of memory, link it to the head of the list of arenas,
769and split it into a list of free SVs.
770
771 void sv_add_arena(char* ptr, U32 size, U32 flags)
772
773=for hackers
774Found in file sv.c
775
776=item sv_clean_all
777
778Decrement the refcnt of each remaining SV, possibly triggering a
779cleanup. This function may have to be called multiple times to free
8fb26106 780SVs which are in complex self-referential hierarchies.
645c22ef
DM
781
782 I32 sv_clean_all()
783
784=for hackers
785Found in file sv.c
786
787=item sv_clean_objs
788
789Attempt to destroy all objects not yet freed
790
791 void sv_clean_objs()
792
793=for hackers
794Found in file sv.c
795
796=item sv_free_arenas
797
798Deallocate the memory used by all arenas. Note that all the individual SV
799heads and bodies within the arenas must already have been freed.
800
801 void sv_free_arenas()
802
803=for hackers
804Found in file sv.c
805
a4f1a029 806
954c1994
GS
807=back
808
809=head1 AUTHORS
810
1c846c1f
NIS
811The autodocumentation system was originally added to the Perl core by
812Benjamin Stuhl. Documentation is by whoever was kind enough to
954c1994
GS
813document their functions.
814
815=head1 SEE ALSO
816
817perlguts(1), perlapi(1)
818