| 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 |