dwww Home | Manual pages | Find package

Devel::CallChecker(3pmUser Contributed Perl DocumentatiDevel::CallChecker(3pm)

NAME
       Devel::CallChecker - custom op checking attached to subroutines

SYNOPSIS
           # to generate header prior to XS compilation

           perl -MDevel::CallChecker=callchecker0_h \
               -e 'print callchecker0_h' > callchecker0.h

           # in Perl part of module

           use Devel::CallChecker;

           /* in XS */

           #include "callchecker0.h"

           cv_get_call_checker(cv, &ckfun, &ckobj);
           static OP *my_ckfun(pTHX_ OP *o, GV *namegv, SV *ckobj);
           cv_set_call_checker(cv, my_ckfun, ckobj);

DESCRIPTION
       This module makes some new features of the Perl 5.14.0 C API available
       to XS modules running on older versions of Perl.  The features are
       centred around the function "cv_set_call_checker", which allows XS code
       to attach a magical annotation to a Perl subroutine, resulting in
       resolvable calls to that subroutine being mutated at compile time by
       arbitrary C code.  This module makes "cv_set_call_checker" and several
       supporting functions available.  (It is possible to achieve the effect
       of "cv_set_call_checker" from XS code on much earlier Perl versions,
       but it is painful to achieve without the centralised facility.)

       This module provides the implementation of the functions at runtime (on
       Perls where they are not provided by the core).  It also, at compile
       time, supplies the C header file and link library which provide access
       to the functions.  In normal use, "callchecker0_h" and
       "callchecker_linkable" should be called at build time (not authoring
       time) for the module that wishes to use the C functions.

CONSTANTS
       callchecker0_h
           Content of a C header file, intended to be named
           ""callchecker0.h"".  It is to be included in XS code, and "perl.h"
           must be included first.  When the XS module is loaded at runtime,
           the "Devel::CallChecker" module must be loaded first.  This will
           result in the Perl API functions "rv2cv_op_cv",
           "ck_entersub_args_list", "ck_entersub_args_proto",
           "ck_entersub_args_proto_or_list", "cv_get_call_checker", and
           "cv_set_call_checker", as defined below and in the Perl 5.14.0 API,
           being available to the XS code.

       callchecker_linkable
           List of names of files that must be used as additional objects when
           linking an XS module that uses the C functions supplied by this
           module.  This list will be empty on many platforms.

C FUNCTIONS
       rv2cv_op_cv
           Examines an op, which is expected to identify a subroutine at
           runtime, and attempts to determine at compile time which subroutine
           it identifies.  This is normally used during Perl compilation to
           determine whether a prototype can be applied to a function call.
           cvop is the op being considered, normally an "rv2cv" op.  A pointer
           to the identified subroutine is returned, if it could be determined
           statically, and a null pointer is returned if it was not possible
           to determine statically.

           Whether the subroutine is statically identifiable is determined in
           accordance with the prevailing standards of the Perl version being
           used.  The same criteria are used that the core uses to determine
           whether to apply a prototype to a subroutine call.  From version
           5.11.2 onwards, the subroutine can be determined if the RV that the
           "rv2cv" is to operate on is provided by a suitable "gv" or "const"
           op.  Prior to 5.11.2, only a "gv" op will do.  A "gv" op is
           suitable if the GV's CV slot is populated.  A "const" op is
           suitable if the constant value must be an RV pointing to a CV.
           Details of this process may change in future versions of Perl.

           If the "rv2cv" op has the "OPpENTERSUB_AMPER" flag set then no
           attempt is made to identify the subroutine statically: this flag is
           used to suppress compile-time magic on a subroutine call, forcing
           it to use default runtime behaviour.

           If flags has the bit "RV2CVOPCV_MARK_EARLY" set, then the handling
           of a GV reference is modified.  If a GV was examined and its CV
           slot was found to be empty, then the "gv" op has the "OPpEARLY_CV"
           flag set.  If the op is not optimised away, and the CV slot is
           later populated with a subroutine having a prototype, that flag
           eventually triggers the warning "called too early to check
           prototype".

           If flags has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
           of returning a pointer to the subroutine it returns a pointer to
           the GV giving the most appropriate name for the subroutine in this
           context.  Normally this is just the "CvGV" of the subroutine, but
           for an anonymous ("CvANON") subroutine that is referenced through a
           GV it will be the referencing GV.  The resulting "GV*" is cast to
           "CV*" to be returned.  A null pointer is returned as usual if there
           is no statically-determinable subroutine.

               CV *rv2cv_op_cv(OP *cvop, U32 flags)

       cv_get_call_checker
           Retrieves the function that will be used to fix up a call to cv.
           Specifically, the function is applied to an "entersub" op tree for
           a subroutine call, not marked with "&", where the callee can be
           identified at compile time as cv.

           The C-level function pointer is returned in *ckfun_p, and an SV
           argument for it is returned in *ckobj_p.  The function is intended
           to be called in this manner:

               entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

           In this call, entersubop is a pointer to the "entersub" op, which
           may be replaced by the check function, and namegv is a GV supplying
           the name that should be used by the check function to refer to the
           callee of the "entersub" op if it needs to emit any diagnostics.
           It is permitted to apply the check function in non-standard
           situations, such as to a call to a different subroutine or to a
           method call.

           By default, the function is Perl_ck_entersub_args_proto_or_list,
           and the SV parameter is cv itself.  This implements standard
           prototype processing.  It can be changed, for a particular
           subroutine, by "cv_set_call_checker".

               void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
                       SV **ckobj_p)

       cv_set_call_checker
           Sets the function that will be used to fix up a call to cv.
           Specifically, the function is applied to an "entersub" op tree for
           a subroutine call, not marked with "&", where the callee can be
           identified at compile time as cv.

           The C-level function pointer is supplied in ckfun, and an SV
           argument for it is supplied in ckobj.  The function is intended to
           be called in this manner:

               entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

           In this call, entersubop is a pointer to the "entersub" op, which
           may be replaced by the check function, and namegv is a GV supplying
           the name that should be used by the check function to refer to the
           callee of the "entersub" op if it needs to emit any diagnostics.
           It is permitted to apply the check function in non-standard
           situations, such as to a call to a different subroutine or to a
           method call.

           The current setting for a particular CV can be retrieved by
           "cv_get_call_checker".

               void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
                       SV *ckobj)

       ck_entersub_args_list
           Performs the default fixup of the arguments part of an "entersub"
           op tree.  This consists of applying list context to each of the
           argument ops.  This is the standard treatment used on a call marked
           with "&", or a method call, or a call through a subroutine
           reference, or any other call where the callee can't be identified
           at compile time, or a call where the callee has no prototype.

               OP *ck_entersub_args_list(OP *entersubop)

       ck_entersub_args_proto
           Performs the fixup of the arguments part of an "entersub" op tree
           based on a subroutine prototype.  This makes various modifications
           to the argument ops, from applying context up to inserting "refgen"
           ops, and checking the number and syntactic types of arguments, as
           directed by the prototype.  This is the standard treatment used on
           a subroutine call, not marked with "&", where the callee can be
           identified at compile time and has a prototype.

           protosv supplies the subroutine prototype to be applied to the
           call.  It may be a normal defined scalar, of which the string value
           will be used.  Alternatively, for convenience, it may be a
           subroutine object (a "CV*" that has been cast to "SV*") which has a
           prototype.  The prototype supplied, in whichever form, does not
           need to match the actual callee referenced by the op tree.

           If the argument ops disagree with the prototype, for example by
           having an unacceptable number of arguments, a valid op tree is
           returned anyway.  The error is reflected in the parser state,
           normally resulting in a single exception at the top level of
           parsing which covers all the compilation errors that occurred.  In
           the error message, the callee is referred to by the name defined by
           the namegv parameter.

               OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
                       SV *protosv)

       ck_entersub_args_proto_or_list
           Performs the fixup of the arguments part of an "entersub" op tree
           either based on a subroutine prototype or using default list-
           context processing.  This is the standard treatment used on a
           subroutine call, not marked with "&", where the callee can be
           identified at compile time.

           protosv supplies the subroutine prototype to be applied to the
           call, or indicates that there is no prototype.  It may be a normal
           scalar, in which case if it is defined then the string value will
           be used as a prototype, and if it is undefined then there is no
           prototype.  Alternatively, for convenience, it may be a subroutine
           object (a "CV*" that has been cast to "SV*"), of which the
           prototype will be used if it has one.  The prototype (or lack
           thereof) supplied, in whichever form, does not need to match the
           actual callee referenced by the op tree.

           If the argument ops disagree with the prototype, for example by
           having an unacceptable number of arguments, a valid op tree is
           returned anyway.  The error is reflected in the parser state,
           normally resulting in a single exception at the top level of
           parsing which covers all the compilation errors that occurred.  In
           the error message, the callee is referred to by the name defined by
           the namegv parameter.

               OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
                       SV *protosv)

SEE ALSO
       B::CallChecker, Devel::CallParser, "cv_set_call_checker" in perlapi

AUTHOR
       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT
       Copyright (C) 2011, 2012, 2013, 2015, 2017 Andrew Main (Zefram)
       <zefram@fysh.org>

LICENSE
       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.34.0                      2022-02-06           Devel::CallChecker(3pm)

Generated by dwww version 1.14 on Fri Jan 24 06:34:36 CET 2025.