diff options
Diffstat (limited to 'upstream/fedora-40/man1/perlmroapi.1')
| -rw-r--r-- | upstream/fedora-40/man1/perlmroapi.1 | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/perlmroapi.1 b/upstream/fedora-40/man1/perlmroapi.1 new file mode 100644 index 00000000..ada82686 --- /dev/null +++ b/upstream/fedora-40/man1/perlmroapi.1 @@ -0,0 +1,155 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLMROAPI 1" +.TH PERLMROAPI 1 2024-01-25 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlmroapi \- Perl method resolution plugin interface +.SH DESCRIPTION +.IX Header "DESCRIPTION" +As of Perl 5.10.1 there is a new interface for plugging and using method +resolution orders other than the default (linear depth first search). +The C3 method resolution order added in 5.10.0 has been re-implemented as +a plugin, without changing its Perl-space interface. +.PP +Each plugin should register itself by providing +the following structure +.PP +.Vb 7 +\& struct mro_alg { +\& AV *(*resolve)(pTHX_ HV *stash, U32 level); +\& const char *name; +\& U16 length; +\& U16 kflags; +\& U32 hash; +\& }; +.Ve +.PP +and calling \f(CW\*(C`Perl_mro_register\*(C'\fR: +.PP +.Vb 1 +\& Perl_mro_register(aTHX_ &my_mro_alg); +.Ve +.IP resolve 4 +.IX Item "resolve" +Pointer to the linearisation function, described below. +.IP name 4 +.IX Item "name" +Name of the MRO, either in ISO\-8859\-1 or UTF\-8. +.IP length 4 +.IX Item "length" +Length of the name. +.IP kflags 4 +.IX Item "kflags" +If the name is given in UTF\-8, set this to \f(CW\*(C`HVhek_UTF8\*(C'\fR. The value is passed +direct as the parameter \fIkflags\fR to \f(CWhv_common()\fR. +.IP hash 4 +.IX Item "hash" +A precomputed hash value for the MRO's name, or 0. +.SH Callbacks +.IX Header "Callbacks" +The \f(CW\*(C`resolve\*(C'\fR function is called to generate a linearised ISA for the +given stash, using this MRO. It is called with a pointer to the stash, and +a \fIlevel\fR of 0. The core always sets \fIlevel\fR to 0 when it calls your +function \- the parameter is provided to allow your implementation to track +depth if it needs to recurse. +.PP +The function should return a reference to an array containing string SVs +giving the names of parent classes in order. The names of the classes should +be the result of calling \f(CWHvENAME()\fR on the stash. In those cases where +\&\f(CWHvENAME()\fR returns null, \f(CWHvNAME()\fR should be used instead. +.PP +The caller is responsible for incrementing the reference count of the array +returned if it wants to keep the structure. Hence, if you have created a +temporary value that you keep no pointer to, \f(CWsv_2mortal()\fR to ensure that +it is disposed of correctly. If you have cached your return value, then +return a pointer to it without changing the reference count. +.SH Caching +.IX Header "Caching" +Computing MROs can be expensive. The implementation provides a cache, in +which you can store a single \f(CW\*(C`SV *\*(C'\fR, or anything that can be cast to +\&\f(CW\*(C`SV *\*(C'\fR, such as \f(CW\*(C`AV *\*(C'\fR. To read your private value, use the macro +\&\f(CWMRO_GET_PRIVATE_DATA()\fR, passing it the \f(CW\*(C`mro_meta\*(C'\fR structure from the +stash, and a pointer to your \f(CW\*(C`mro_alg\*(C'\fR structure: +.PP +.Vb 2 +\& meta = HvMROMETA(stash); +\& private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg); +.Ve +.PP +To set your private value, call \f(CWPerl_mro_set_private_data()\fR: +.PP +.Vb 1 +\& Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv); +.Ve +.PP +The private data cache will take ownership of a reference to private_sv, +much the same way that \f(CWhv_store()\fR takes ownership of a reference to the +value that you pass it. +.SH Examples +.IX Header "Examples" +For examples of MRO implementations, see \f(CWS_mro_get_linear_isa_c3()\fR +and the \f(CW\*(C`BOOT:\*(C'\fR section of \fIext/mro/mro.xs\fR, and +\&\f(CWS_mro_get_linear_isa_dfs()\fR in \fImro_core.c\fR +.SH AUTHORS +.IX Header "AUTHORS" +The implementation of the C3 MRO and switchable MROs within the perl core was +written by Brandon L Black. Nicholas Clark created the pluggable interface, +refactored Brandon's implementation to work with it, and wrote this document. |