Debian Codegraph @

upstream/fedora-44/man1/perlclassguts.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLCLASSGUTS 1"
61 .TH PERLCLASSGUTS 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlclassguts \- Internals of how "feature \*(Aqclass\*(Aq" and class syntax works
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This document provides in\-depth information about the way in which the perl
71 interpreter implements the \f(CW\*(C`feature \*(Aqclass\*(Aq\*(C'\fR syntax and overall behaviour.
72 It is not intended as an end\-user guide on how to use the feature. For that,
73 see perlclass.
74 .PP
75 The reader is assumed to be generally familiar with the perl interpreter
76 internals overall. For a more general overview of these details, see also
77 perlguts.
78 .SH "DATA STORAGE"
79 .IX Header "DATA STORAGE"
80 .SS Classes
81 .IX Subsection "Classes"
82 A class is fundamentally a package, and exists in the symbol table as an HV
83 with an aux structure in exactly the same way as a non\-class package. It is
84 distinguished from a non\-class package by the fact that the
85 \&\f(CWHvSTASH_IS_CLASS()\fR macro will return true on it.
86 .PP
87 Extra information relating to it being a class is stored in the
88 \&\f(CW\*(C`struct xpvhv_aux\*(C'\fR structure attached to the stash, in the following fields:
89 .PP
90 .Vb 6
91 \& HV *xhv_class_superclass;
92 \& CV *xhv_class_initfields_cv;
93 \& AV *xhv_class_adjust_blocks;
94 \& PADNAMELIST *xhv_class_fields;
95 \& PADOFFSET xhv_class_next_fieldix;
96 \& HV *xhv_class_param_map;
97 .Ve
98 .IP \(bu 4
99 \&\f(CW\*(C`xhv_class_superclass\*(C'\fR will be \f(CW\*(C`NULL\*(C'\fR for a class with no superclass. It
100 will point directly to the stash of the parent class if one has been set with
101 the \f(CW:isa()\fR class attribute.
102 .IP \(bu 4
103 \&\f(CW\*(C`xhv_class_initfields_cv\*(C'\fR will contain a \f(CW\*(C`CV *\*(C'\fR pointing to a function to be
104 invoked as part of the constructor of this class or any subclass thereof. This
105 CV is responsible for initializing all the fields defined by this class for a
106 new instance. This CV will be an anonymous real function \- i.e. while it has no
107 name and no GV, it is \fInot\fR a protosub and may be directly invoked.
108 .IP \(bu 4
109 \&\f(CW\*(C`xhv_class_adjust_blocks\*(C'\fR may point to an AV containing CV pointers to each of
110 the \f(CW\*(C`ADJUST\*(C'\fR blocks defined on the class. If the class has a superclass, this
111 array will additionally contain duplicate pointers of the CVs of its parent
112 class. The AV is created lazily the first time an element is pushed to it; it
113 is valid for there not to be one, and this pointer will be \f(CW\*(C`NULL\*(C'\fR in that
114 case.
115 .Sp
116 The CVs are stored directly, not via RVs. Each CV will be an anonymous real
117 function.
118 .IP \(bu 4
119 \&\f(CW\*(C`xhv_class_fields\*(C'\fR will point to a \f(CW\*(C`PADNAMELIST\*(C'\fR containing \f(CW\*(C`PADNAME\*(C'\fRs,
120 each being one defined field of the class. They are stored in order of
121 declaration. Note however, that the index into this array will not necessarily
122 be equal to the \f(CW\*(C`fieldix\*(C'\fR of each field, because in the case of a subclass,
123 the array will begin at zero but the index of the first field in it will be
124 non\-zero if its parent class contains any fields at all.
125 .Sp
126 For more information on how individual fields are represented, see "Fields".
127 .IP \(bu 4
128 \&\f(CW\*(C`xhv_class_next_fieldix\*(C'\fR gives the field index that will be assigned to the
129 next field to be added to the class. It is only useful at compile\-time.
130 .IP \(bu 4
131 \&\f(CW\*(C`xhv_class_param_map\*(C'\fR may point to an HV which maps field \f(CW\*(C`:param\*(C'\fR attribute
132 names to the field index of the field with that name. This mapping is copied
133 from parent classes; each class will contain the sum total of all its parents
134 in addition to its own.
135 .SS Fields
136 .IX Subsection "Fields"
137 A field is still fundamentally a lexical variable declared in a scope, and
138 exists in the \f(CW\*(C`PADNAMELIST\*(C'\fR of its corresponding CV. Methods and other
139 method\-like CVs can still capture them exactly as they can with regular
140 lexicals. A field is distinguished from other kinds of pad entry in that the
141 \&\f(CWPadnameIsFIELD()\fR macro will return true on it.
142 .PP
143 Extra information relating to it being a field is stored in an additional
144 structure accessible via the \f(CWPadnameFIELDINFO()\fR macro on the padname. This
145 structure has the following fields:
146 .PP
147 .Vb 6
148 \& PADOFFSET fieldix;
149 \& HV *fieldstash;
150 \& OP *defop;
151 \& SV *paramname;
152 \& bool def_if_undef;
153 \& bool def_if_false;
154 .Ve
155 .IP \(bu 4
156 \&\f(CW\*(C`fieldix\*(C'\fR stores the "field index" of the field; that is, the index into the
157 instance field array where this field\*(Aqs value will be stored. Note that the
158 first index in the array is not specially reserved. The first field in a class
159 will start from field index 0.
160 .IP \(bu 4
161 \&\f(CW\*(C`fieldstash\*(C'\fR stores a pointer to the stash of the class that defined this
162 field. This is necessary in case there are multiple classes defined within the
163 same scope; it is used to disambiguate the fields of each.
164 .Sp
165 .Vb 4
166 \& {
167 \& class C1; field $x;
168 \& class C2; field $x;
169 \& }
170 .Ve
171 .IP \(bu 4
172 \&\f(CW\*(C`defop\*(C'\fR may store a pointer to a defaulting expression optree for this field.
173 Defaulting expressions are optional; this field may be \f(CW\*(C`NULL\*(C'\fR.
174 .IP \(bu 4
175 \&\f(CW\*(C`paramname\*(C'\fR may point to a regular string SV containing the \f(CW\*(C`:param\*(C'\fR name
176 attribute given to the field. If none, it will be \f(CW\*(C`NULL\*(C'\fR.
177 .IP \(bu 4
178 One of \f(CW\*(C`def_if_undef\*(C'\fR and \f(CW\*(C`def_if_false\*(C'\fR will be true if the defaulting
179 expression was set using the \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR operators respectively.
180 .SS Methods
181 .IX Subsection "Methods"
182 A method is still fundamentally a CV, and has the same basic representation as
183 one. It has an optree and a pad, and is stored via a GV in the stash of its
184 containing package. It is distinguished from a non\-method CV by the fact that
185 the \f(CWCvIsMETHOD()\fR macro will return true on it.
186 .PP
187 (Note: This macro should not be confused with the one that was previously
188 called \f(CWCvMETHOD()\fR. That one does not relate to the class system, and was
189 renamed to \f(CWCvNOWARN_AMBIGUOUS()\fR to avoid this confusion.)
190 .PP
191 There is currently no extra information that needs to be stored about a method
192 CV, so the structure does not add any new fields.
193 .SS Instances
194 .IX Subsection "Instances"
195 Object instances are represented by an entirely new SV type, whose base type
196 is \f(CW\*(C`SVt_PVOBJ\*(C'\fR. This should still be blessed into its class stash and wrapped
197 in an RV in the usual manner for classical object.
198 .PP
199 As these are their own unique container type, distinct from hashes or arrays,
200 the core \f(CW\*(C`builtin::reftype\*(C'\fR function returns a new value when asked about
201 these. That value is \f(CW"OBJECT"\fR.
202 .PP
203 Internally, such an object is an array of SV pointers whose size is fixed at
204 creation time (because the number of fields in a class is known after
205 compilation). An object instance stores the max field index within it (for
206 basic error\-checking on access), and a fixed\-size array of SV pointers storing
207 the individual field values.
208 .PP
209 Fields of array and hash type directly store AV or HV pointers into the array;
210 they are not stored via an intervening RV.
211 .SH API
212 .IX Header "API"
213 The data structures described above are supported by the following API
214 functions.
215 .SS "Class Manipulation"
216 .IX Subsection "Class Manipulation"
217 \fIclass_setup_stash\fR
218 .IX Subsection "class_setup_stash"
219 .PP
220 .Vb 1
221 \& void class_setup_stash(HV *stash);
222 .Ve
223 .PP
224 Called by the parser on encountering the \f(CW\*(C`class\*(C'\fR keyword. It upgrades the
225 stash into being a class and prepares it for receiving class\-specific items
226 like methods and fields.
227 .PP
228 \fIclass_seal_stash\fR
229 .IX Subsection "class_seal_stash"
230 .PP
231 .Vb 1
232 \& void class_seal_stash(HV *stash);
233 .Ve
234 .PP
235 Called by the parser at the end of a \f(CW\*(C`class\*(C'\fR block, or for unit classes its
236 containing scope. This function performs various finalisation activities that
237 are required before instances of the class can be constructed, but could not
238 have been done until all the information about the members of the class is
239 known.
240 .PP
241 Any additions to or modifications of the class under compilation must be
242 performed between these two function calls. Classes cannot be modified once
243 they have been sealed.
244 .PP
245 \fIclass_add_field\fR
246 .IX Subsection "class_add_field"
247 .PP
248 .Vb 1
249 \& void class_add_field(HV *stash, PADNAME *pn);
250 .Ve
251 .PP
252 Called by \fIpad.c\fR as part of defining a new field name in the current pad.
253 Note that this function does \fInot\fR create the padname; that must already be
254 done by \fIpad.c\fR. This API function simply informs the class that the new
255 field name has been created and is now available for it.
256 .PP
257 \fIclass_add_ADJUST\fR
258 .IX Subsection "class_add_ADJUST"
259 .PP
260 .Vb 1
261 \& void class_add_ADJUST(HV *stash, CV *cv);
262 .Ve
263 .PP
264 Called by the parser once it has parsed and constructed a CV for a new
265 \&\f(CW\*(C`ADJUST\*(C'\fR block. This gets added to the list stored by the class.
266 .SS "Field Manipulation"
267 .IX Subsection "Field Manipulation"
268 \fIclass_prepare_initfield_parse\fR
269 .IX Subsection "class_prepare_initfield_parse"
270 .PP
271 .Vb 1
272 \& void class_prepare_initfield_parse();
273 .Ve
274 .PP
275 Called by the parser just before parsing an initializing expression for a
276 field variable. This makes use of a suspended compcv to combine all the field
277 initializing expressions into the same CV.
278 .PP
279 \fIclass_set_field_defop\fR
280 .IX Subsection "class_set_field_defop"
281 .PP
282 .Vb 1
283 \& void class_set_field_defop(PADNAME *pn, OPCODE defmode, OP *defop);
284 .Ve
285 .PP
286 Called by the parser after it has parsed an initializing expression for the
287 field. Sets the defaulting expression and mode of application. \f(CW\*(C`defmode\*(C'\fR
288 should either be zero, or one of \f(CW\*(C`OP_ORASSIGN\*(C'\fR or \f(CW\*(C`OP_DORASSIGN\*(C'\fR depending
289 on the defaulting mode.
290 .PP
291 \fIpadadd_FIELD\fR
292 .IX Subsection "padadd_FIELD"
293 .PP
294 .Vb 1
295 \& #define padadd_FIELD
296 .Ve
297 .PP
298 This flag constant tells the \f(CW\*(C`pad_add_name_*\*(C'\fR family of functions that the
299 new name should be added as a field. There is no need to call
300 \&\f(CWclass_add_field()\fR; this will be done automatically.
301 .SS "Method Manipulation"
302 .IX Subsection "Method Manipulation"
303 \fIclass_prepare_method_parse\fR
304 .IX Subsection "class_prepare_method_parse"
305 .PP
306 .Vb 1
307 \& void class_prepare_method_parse(CV *cv);
308 .Ve
309 .PP
310 Called by the parser after \f(CWstart_subparse()\fR but immediately before doing
311 anything else. This prepares the \f(CW\*(C`PL_compcv\*(C'\fR for parsing a method; arranging
312 for the \f(CW\*(C`CvIsMETHOD\*(C'\fR test to be true, adding the \f(CW$self\fR lexical, and any
313 other activities that may be required.
314 .PP
315 \fIclass_wrap_method_body\fR
316 .IX Subsection "class_wrap_method_body"
317 .PP
318 .Vb 1
319 \& OP *class_wrap_method_body(OP *o);
320 .Ve
321 .PP
322 Called by the parser at the end of parsing a method body into an optree but
323 just before wrapping it in the eventual CV. This function inserts extra ops
324 into the optree to make the method work correctly.
325 .SS "Object Instances"
326 .IX Subsection "Object Instances"
327 \fISVt_PVOBJ\fR
328 .IX Subsection "SVt_PVOBJ"
329 .PP
330 .Vb 1
331 \& #define SVt_PVOBJ
332 .Ve
333 .PP
334 An SV type constant used for comparison with the \f(CWSvTYPE()\fR macro.
335 .PP
336 \fIObjectMAXFIELD\fR
337 .IX Subsection "ObjectMAXFIELD"
338 .PP
339 .Vb 1
340 \& SSize_t ObjectMAXFIELD(sv);
341 .Ve
342 .PP
343 A function\-like macro that obtains the maximum valid field index that can be
344 accessed from the \f(CW\*(C`ObjectFIELDS\*(C'\fR array.
345 .PP
346 \fIObjectFIELDS\fR
347 .IX Subsection "ObjectFIELDS"
348 .PP
349 .Vb 1
350 \& SV **ObjectFIELDS(sv);
351 .Ve
352 .PP
353 A function\-like macro that obtains the fields array directly out of an object
354 instance. Fields can be accessed by their field index, from 0 up to the maximum
355 valid index given by \f(CW\*(C`ObjectMAXFIELD\*(C'\fR.
356 .SH OPCODES
357 .IX Header "OPCODES"
358 .SS OP_METHSTART
359 .IX Subsection "OP_METHSTART"
360 .Vb 1
361 \& newUNOP_AUX(OP_METHSTART, ...);
362 .Ve
363 .PP
364 An \f(CW\*(C`OP_METHSTART\*(C'\fR is an \f(CW\*(C`UNOP_AUX\*(C'\fR which must be present at the start of a
365 method CV in order to make it work properly. This is inserted by
366 \&\f(CWclass_wrap_method_body()\fR, and even appears before any optree fragment
367 associated with signature argument checking or extraction.
368 .PP
369 This op is responsible for shifting the value of \f(CW$self\fR out of the arguments
370 list and binding any field variables that the method requires access to into
371 the pad. The AUX vector will contain details of the field/pad index pairings
372 required.
373 .PP
374 This op also performs sanity checking on the invocant value. It checks that it
375 is definitely an object reference of a compatible class type. If not, an
376 exception is thrown.
377 .PP
378 If the \f(CW\*(C`op_private\*(C'\fR field includes the \f(CW\*(C`OPpINITFIELDS\*(C'\fR flag, this indicates
379 that the op begins the special \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR CV. In this case it
380 should additionally take the second value from the arguments list, which
381 should be a plain HV pointer (\fIdirectly\fR, not via RV). and bind it to the
382 second pad slot, where the generated optree will expect to find it.
383 .SS OP_INITFIELD
384 .IX Subsection "OP_INITFIELD"
385 An \f(CW\*(C`OP_INITFIELD\*(C'\fR is only invoked as part of the \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR
386 CV during the construction phase of an instance. This is the time that the
387 individual SVs that make up the mutable fields of the instance (including AVs
388 and HVs) are actually assigned into the \f(CW\*(C`ObjectFIELDS\*(C'\fR array. The
389 \&\f(CW\*(C`OPpINITFIELD_AV\*(C'\fR and \f(CW\*(C`OPpINITFIELD_HV\*(C'\fR private flags indicate whether it is
390 creating an AV or HV; if neither is set then an SV is created.
391 .PP
392 If the op has the \f(CW\*(C`OPf_STACKED\*(C'\fR flag it expects to find an initializing value
393 on the stack. For SVs this is the topmost SV on the data stack. For AVs and
394 HVs it expects a marked list.
395 .SH "COMPILE\-TIME BEHAVIOUR"
396 .IX Header "COMPILE-TIME BEHAVIOUR"
397 .ie n .SS """ADJUST"" Phasers"
398 .el .SS "\f(CWADJUST\fP Phasers"
399 .IX Subsection "ADJUST Phasers"
400 During compiletime, parsing of an \f(CW\*(C`ADJUST\*(C'\fR phaser is handled in a
401 fundamentally different way to the existing perl phasers (\f(CW\*(C`BEGIN\*(C'\fR, etc...)
402 .PP
403 Rather than taking the usual route, the tokenizer recognises that the
404 \&\f(CW\*(C`ADJUST\*(C'\fR keyword introduces a phaser block. The parser then parses the body
405 of this block similarly to how it would parse an (anonymous) method body,
406 creating a CV that has no name GV. This is then inserted directly into the
407 class information by calling \f(CW\*(C`class_add_ADJUST\*(C'\fR, entirely bypassing the
408 symbol table.
409 .SS Attributes
410 .IX Subsection "Attributes"
411 During compilation, attributes of both classes and fields are handled in a
412 different way to existing perl attributes on subroutines and lexical
413 variables.
414 .PP
415 The parser still forms an \f(CW\*(C`OP_LIST\*(C'\fR optree of \f(CW\*(C`OP_CONST\*(C'\fR nodes, but these
416 are passed to the \f(CW\*(C`class_apply_attributes\*(C'\fR or \f(CW\*(C`class_apply_field_attributes\*(C'\fR
417 functions. Rather than using a class lookup for a method in the class being
418 parsed, a fixed internal list of known attributes is used to find functions to
419 apply the attribute to the class or field. In future this may support
420 user\-supplied extension attribute, though at present it only recognises ones
421 defined by the core itself.
422 .SS "Field Initializing Expressions"
423 .IX Subsection "Field Initializing Expressions"
424 During compilation, the parser makes use of a suspended compcv when parsing
425 the defaulting expression for a field. All the expressions for all the fields
426 in the class share the same suspended compcv, which is then compiled up into
427 the same internal CV called by the constructor to initialize all the fields
428 provided by that class.
429 .SH "RUNTIME BEHAVIOUR"
430 .IX Header "RUNTIME BEHAVIOUR"
431 .SS Constructor
432 .IX Subsection "Constructor"
433 The generated constructor for a class itself is an XSUB which performs three
434 tasks in order: it creates the instance SV itself, invokes the field
435 initializers, then invokes the ADJUST block CVs. The constructor for any class
436 is always the same basic shape, regardless of whether the class has a
437 superclass or not.
438 .PP
439 The field initializers are collected into a generated optree\-based CV called
440 the field initializer CV. This is the CV which contains all the optree
441 fragments for the field initializing expressions. When invoked, the field
442 initializer CV might make a chained call to the superclass initializer if one
443 exists, before invoking all of the individual field initialization ops. The
444 field initializer CV is invoked with two items on the stack; being the
445 instance SV and a direct HV containing the constructor parameters. Note
446 carefully: this HV is passed \fIdirectly\fR, not via an RV reference. This is
447 permitted because both the caller and the callee are directly generated code
448 and not arbitrary pure\-perl subroutines.
449 .PP
450 The ADJUST block CVs are all collected into a single flat list, merging all of
451 the ones defined by the superclass as well. They are all invoked in order,
452 after the field initializer CV.
453 .ie n .SS "$self Access During Methods"
454 .el .SS "\f(CW$self\fP Access During Methods"
455 .IX Subsection "$self Access During Methods"
456 When \f(CWclass_prepare_method_parse()\fR is called, it arranges that the pad of
457 the new CV body will begin with a lexical called \f(CW$self\fR. Because the pad
458 should be freshly\-created at this point, this will have the pad index of 1.
459 The function checks this and aborts if that is not true.
460 .PP
461 Because of this fact, code within the body of a method or method\-like CV can
462 reliably use pad index 1 to obtain the invocant reference. The \f(CW\*(C`OP_INITFIELD\*(C'\fR
463 opcode also relies on this fact.
464 .PP
465 In similar fashion, during the \f(CW\*(C`xhv_class_initfields_cv\*(C'\fR the next pad slot is
466 relied on to store the constructor parameters HV, at pad index 2.
467 .SH AUTHORS
468 .IX Header "AUTHORS"
469 Paul Evans