diff --git a/gv.c b/gv.c index bc0db81271f5..6bd190b6b49a 100644 --- a/gv.c +++ b/gv.c @@ -723,55 +723,101 @@ S_maybe_add_coresub(pTHX_ HV * const stash, GV *gv, /* =for apidoc gv_fetchmeth +=for apidoc_item gv_fetchmeth_autoload =for apidoc_item gv_fetchmeth_pv +=for apidoc_item gv_fetchmeth_pv_autoload =for apidoc_item gv_fetchmeth_pvn +=for apidoc_item gv_fetchmeth_pvn_autoload =for apidoc_item gv_fetchmeth_sv +=for apidoc_item gv_fetchmeth_sv_autoload These each look for a glob with name C, containing a defined subroutine, returning the GV of that glob if found, or C if not. -C is always searched (first), unless it is C. +You probably want to use the C> family of functions +instead. -If C is NULL, or was searched but nothing was found in it, and the -C bit is set in C, stashes accessible via C<@ISA> are searched -next. Searching is conducted according to L order|perlmroapi>. +Searching is always done in the following order, with some steps skipped +depending on various criteria. The first match found is used, ending the +search. C and C lack a flags +parameter, so in the following, consider C to be zero for those two +functions. -Finally, if no matches were found so far, and the C flag in -C is not set, C is searched. +=over + +=item 1 + +C is searched first, unless C either is NULL or C is +set in C. + +=item 2 + +Stashes accessible via C<@ISA> are searched next. + +Searching is conducted according to L order|perlmroapi>. + +=item 3 + +C is searched unless C is set. + +=item 4 + +Autoloaded subroutines are then looked for, but only for the forms whose names +end in C<_autoload>, and when C is not NULL and C is not set. + +=back -The argument C should be either 0 or -1. If -1, the function will -return without any side effects or caching. If 0, the function makes sure -there is a glob named C in C, creating one if necessary. -The subroutine slot in the glob will be set to any subroutine found in the -C and C search, hence caching any C result. Note that -subroutines found in C are not cached. +The argument C should be either 0 or -1. + +=over + +=item If -1 + +No method caching is done. + +=item If 0 + +If C is not set in C, the method found is cached in C. + +If C is set in C, the method is cached in the super +cache for C. + +If the method is not found a negative cache entry is added. + +Note that subroutines found in C are not cached, +though this may change. + +=back The GV returned from these may be a method cache entry, which is not visible to -Perl code. So when calling C, you should not use the GV directly; +Perl code. So when calling C>, you should not use the GV directly; instead, you should use the method's CV, which can be obtained from the GV with -the C macro. +the C macro. For an autoloaded subroutine without a stub, C of +the result may be zero. The only other significant value for C is C, indicating that -C is to be treated as being encoded in UTF-8. +C is to be treated as being encoded in UTF-8. Since plain +C and C lack a C parameter, C +is never UTF-8. -Plain C lacks a C parameter, hence always searches in -C, then C, and C is never UTF-8. Otherwise it is -exactly like C. +Otherwise, the functions behave identically, except as noted below. -The other forms do have a C parameter, and differ only in how the glob -name is specified. +In C and C, C is a C language +NUL-terminated string. -In C, C is a C language NUL-terminated string. +In C, C, C, and +C, C points to the first byte of the name, and +an additional parameter, C, specifies its length in bytes. Hence, the +name may contain embedded-NUL characters. -In C, C points to the first byte of the name, and an -additional parameter, C, specifies its length in bytes. Hence, the name -may contain embedded-NUL characters. - -In C, C<*name> is an SV, and the name is the PV extracted from -that, using L>. If the SV is marked as being in UTF-8, the extracted -PV will also be. +In C and C, C<*name> is an SV, and +the name is the PV extracted from that, using C>. If the SV is marked +as being in UTF-8, the extracted PV will also be. Including C in +C will force the name to be considered to be UTF-8 even if the SV is +not so marked. =for apidoc Amnh||GV_SUPER +=for apidoc Amnh||GV_NOUNIVERSAL =cut */ @@ -996,20 +1042,6 @@ Perl_gv_fetchmeth_pvn(pTHX_ HV *stash, const char *name, STRLEN len, I32 level, return gv_fetchmeth_internal(stash, NULL, name, len, level, flags); } -/* -=for apidoc gv_fetchmeth_autoload - -This is the old form of L, which has no flags -parameter. - -=for apidoc gv_fetchmeth_sv_autoload - -Exactly like L, but takes the name string in the form -of an SV instead of a string/length pair. - -=cut -*/ - GV * Perl_gv_fetchmeth_sv_autoload(pTHX_ HV *stash, SV *namesv, I32 level, U32 flags) { @@ -1022,15 +1054,6 @@ Perl_gv_fetchmeth_sv_autoload(pTHX_ HV *stash, SV *namesv, I32 level, U32 flags) return gv_fetchmeth_pvn_autoload(stash, namepv, namelen, level, flags); } -/* -=for apidoc gv_fetchmeth_pv_autoload - -Exactly like L, but takes a nul-terminated string -instead of a string/length pair. - -=cut -*/ - GV * Perl_gv_fetchmeth_pv_autoload(pTHX_ HV *stash, const char *name, I32 level, U32 flags) { @@ -1038,21 +1061,6 @@ Perl_gv_fetchmeth_pv_autoload(pTHX_ HV *stash, const char *name, I32 level, U32 return gv_fetchmeth_pvn_autoload(stash, name, strlen(name), level, flags); } -/* -=for apidoc gv_fetchmeth_pvn_autoload - -Same as C, but looks for autoloaded subroutines too. -Returns a glob for the subroutine. - -For an autoloaded subroutine without a GV, will create a GV even -if C. For an autoloaded subroutine without a stub, C -of the result may be zero. - -Currently, the only significant value for C is C. - -=cut -*/ - GV * Perl_gv_fetchmeth_pvn_autoload(pTHX_ HV *stash, const char *name, STRLEN len, I32 level, U32 flags) {