diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlmroapi.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlmroapi.pod | 102 |
1 files changed, 0 insertions, 102 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod b/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod deleted file mode 100644 index 54da7dded25..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlmroapi.pod +++ /dev/null @@ -1,102 +0,0 @@ -=head1 NAME - -perlmroapi - Perl method resolution plugin interface - -=head1 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. - -Each plugin should register itself by providing -the following structure - - struct mro_alg { - AV *(*resolve)(pTHX_ HV *stash, U32 level); - const char *name; - U16 length; - U16 kflags; - U32 hash; - }; - -and calling C<Perl_mro_register>: - - Perl_mro_register(aTHX_ &my_mro_alg); - -=over 4 - -=item resolve - -Pointer to the linearisation function, described below. - -=item name - -Name of the MRO, either in ISO-8859-1 or UTF-8. - -=item length - -Length of the name. - -=item kflags - -If the name is given in UTF-8, set this to C<HVhek_UTF8>. The value is passed -direct as the parameter I<kflags> to C<hv_common()>. - -=item hash - -A precomputed hash value for the MRO's name, or 0. - -=back - -=head1 Callbacks - -The C<resolve> 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 I<level> of 0. The core always sets I<level> to 0 when it calls your -function - the parameter is provided to allow your implementation to track -depth if it needs to recurse. - -The function should return a reference to an array containing the parent -classes in order. The names of the classes should be the result of calling -C<HvENAME()> on the stash. In those cases where C<HvENAME()> returns null, -C<HvNAME()> should be used instead. - -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, C<sv_2mortal()> 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. - -=head1 Caching - -Computing MROs can be expensive. The implementation provides a cache, in -which you can store a single C<SV *>, or anything that can be cast to -C<SV *>, such as C<AV *>. To read your private value, use the macro -C<MRO_GET_PRIVATE_DATA()>, passing it the C<mro_meta> structure from the -stash, and a pointer to your C<mro_alg> structure: - - meta = HvMROMETA(stash); - private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg); - -To set your private value, call C<Perl_mro_set_private_data()>: - - Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv); - -The private data cache will take ownership of a reference to private_sv, -much the same way that C<hv_store()> takes ownership of a reference to the -value that you pass it. - -=head1 Examples - -For examples of MRO implementations, see C<S_mro_get_linear_isa_c3()> -and the C<BOOT:> section of F<mro/mro.xs>, and C<S_mro_get_linear_isa_dfs()> -in F<mro.c> - -=head1 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. - -=cut |