Debian Codegraph @

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