{ "content": [ { "type": "text", "text": "# Devel::CallChecker (perldoc)\n\n## NAME\n\nDevel::CallChecker - custom op checking attached to subroutines\n\n## SYNOPSIS\n\n# to generate header prior to XS compilation\nperl -MDevel::CallChecker=callchecker0h \\\n-e 'print callchecker0h' > callchecker0.h\n# in Perl part of module\nuse Devel::CallChecker;\n/* in XS */\n#include \"callchecker0.h\"\ncvgetcallchecker(cv, &ckfun, &ckobj);\nstatic OP *myckfun(pTHX OP *o, GV *namegv, SV *ckobj);\ncvsetcallchecker(cv, myckfun, ckobj);\n\n## DESCRIPTION\n\nThis module makes some new features of the Perl 5.14.0 C API available to XS modules running on\nolder versions of Perl. The features are centred around the function \"cvsetcallchecker\",\nwhich allows XS code to attach a magical annotation to a Perl subroutine, resulting in\nresolvable calls to that subroutine being mutated at compile time by arbitrary C code. This\nmodule makes \"cvsetcallchecker\" and several supporting functions available. (It is possible\nto achieve the effect of \"cvsetcallchecker\" from XS code on much earlier Perl versions, but\nit is painful to achieve without the centralised facility.)\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CONSTANTS**\n- **C FUNCTIONS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Devel::CallChecker", "section": "", "mode": "perldoc", "summary": "Devel::CallChecker - custom op checking attached to subroutines", "synopsis": "# to generate header prior to XS compilation\nperl -MDevel::CallChecker=callchecker0h \\\n-e 'print callchecker0h' > callchecker0.h\n# in Perl part of module\nuse Devel::CallChecker;\n/* in XS */\n#include \"callchecker0.h\"\ncvgetcallchecker(cv, &ckfun, &ckobj);\nstatic OP *myckfun(pTHX OP *o, GV *namegv, SV *ckobj);\ncvsetcallchecker(cv, myckfun, ckobj);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 17, "subsections": [] }, { "name": "DESCRIPTION", "lines": 14, "subsections": [] }, { "name": "CONSTANTS", "lines": 13, "subsections": [] }, { "name": "C FUNCTIONS", "lines": 134, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 2, "subsections": [] }, { "name": "LICENSE", "lines": 3, "subsections": [] } ], "sections": { "NAME": { "content": "Devel::CallChecker - custom op checking attached to subroutines\n", "subsections": [] }, "SYNOPSIS": { "content": "# to generate header prior to XS compilation\n\nperl -MDevel::CallChecker=callchecker0h \\\n-e 'print callchecker0h' > callchecker0.h\n\n# in Perl part of module\n\nuse Devel::CallChecker;\n\n/* in XS */\n\n#include \"callchecker0.h\"\n\ncvgetcallchecker(cv, &ckfun, &ckobj);\nstatic OP *myckfun(pTHX OP *o, GV *namegv, SV *ckobj);\ncvsetcallchecker(cv, myckfun, ckobj);\n", "subsections": [] }, "DESCRIPTION": { "content": "This module makes some new features of the Perl 5.14.0 C API available to XS modules running on\nolder versions of Perl. The features are centred around the function \"cvsetcallchecker\",\nwhich allows XS code to attach a magical annotation to a Perl subroutine, resulting in\nresolvable calls to that subroutine being mutated at compile time by arbitrary C code. This\nmodule makes \"cvsetcallchecker\" and several supporting functions available. (It is possible\nto achieve the effect of \"cvsetcallchecker\" from XS code on much earlier Perl versions, but\nit is painful to achieve without the centralised facility.)\n\nThis module provides the implementation of the functions at runtime (on Perls where they are not\nprovided by the core). It also, at compile time, supplies the C header file and link library\nwhich provide access to the functions. In normal use, \"callchecker0h\" and\n\"callcheckerlinkable\" should be called at build time (not authoring time) for the module that\nwishes to use the C functions.\n", "subsections": [] }, "CONSTANTS": { "content": "callchecker0h\nContent of a C header file, intended to be named \"\"callchecker0.h\"\". It is to be included in\nXS code, and \"perl.h\" must be included first. When the XS module is loaded at runtime, the\n\"Devel::CallChecker\" module must be loaded first. This will result in the Perl API functions\n\"rv2cvopcv\", \"ckentersubargslist\", \"ckentersubargsproto\",\n\"ckentersubargsprotoorlist\", \"cvgetcallchecker\", and \"cvsetcallchecker\", as\ndefined below and in the Perl 5.14.0 API, being available to the XS code.\n\ncallcheckerlinkable\nList of names of files that must be used as additional objects when linking an XS module\nthat uses the C functions supplied by this module. This list will be empty on many\nplatforms.\n", "subsections": [] }, "C FUNCTIONS": { "content": "rv2cvopcv\nExamines an op, which is expected to identify a subroutine at runtime, and attempts to\ndetermine at compile time which subroutine it identifies. This is normally used during Perl\ncompilation to determine whether a prototype can be applied to a function call. *cvop* is\nthe op being considered, normally an \"rv2cv\" op. A pointer to the identified subroutine is\nreturned, if it could be determined statically, and a null pointer is returned if it was not\npossible to determine statically.\n\nWhether the subroutine is statically identifiable is determined in accordance with the\nprevailing standards of the Perl version being used. The same criteria are used that the\ncore uses to determine whether to apply a prototype to a subroutine call. From version\n5.11.2 onwards, the subroutine can be determined if the RV that the \"rv2cv\" is to operate on\nis provided by a suitable \"gv\" or \"const\" op. Prior to 5.11.2, only a \"gv\" op will do. A\n\"gv\" op is suitable if the GV's CV slot is populated. A \"const\" op is suitable if the\nconstant value must be an RV pointing to a CV. Details of this process may change in future\nversions of Perl.\n\nIf the \"rv2cv\" op has the \"OPpENTERSUBAMPER\" flag set then no attempt is made to identify\nthe subroutine statically: this flag is used to suppress compile-time magic on a subroutine\ncall, forcing it to use default runtime behaviour.\n\nIf *flags* has the bit \"RV2CVOPCVMARKEARLY\" set, then the handling of a GV reference is\nmodified. If a GV was examined and its CV slot was found to be empty, then the \"gv\" op has\nthe \"OPpEARLYCV\" flag set. If the op is not optimised away, and the CV slot is later\npopulated with a subroutine having a prototype, that flag eventually triggers the warning\n\"called too early to check prototype\".\n\nIf *flags* has the bit \"RV2CVOPCVRETURNNAMEGV\" set, then instead of returning a pointer\nto the subroutine it returns a pointer to the GV giving the most appropriate name for the\nsubroutine in this context. Normally this is just the \"CvGV\" of the subroutine, but for an\nanonymous (\"CvANON\") subroutine that is referenced through a GV it will be the referencing\nGV. The resulting \"GV*\" is cast to \"CV*\" to be returned. A null pointer is returned as usual\nif there is no statically-determinable subroutine.\n\nCV *rv2cvopcv(OP *cvop, U32 flags)\n\ncvgetcallchecker\nRetrieves the function that will be used to fix up a call to *cv*. Specifically, the\nfunction is applied to an \"entersub\" op tree for a subroutine call, not marked with \"&\",\nwhere the callee can be identified at compile time as *cv*.\n\nThe C-level function pointer is returned in ckfunp*, and an SV argument for it is\nreturned in ckobjp*. The function is intended to be called in this manner:\n\nentersubop = (*ckfunp)(aTHX entersubop, namegv, (*ckobjp));\n\nIn this call, *entersubop* is a pointer to the \"entersub\" op, which may be replaced by the\ncheck function, and *namegv* is a GV supplying the name that should be used by the check\nfunction to refer to the callee of the \"entersub\" op if it needs to emit any diagnostics. It\nis permitted to apply the check function in non-standard situations, such as to a call to a\ndifferent subroutine or to a method call.\n\nBy default, the function is Perlckentersubargsprotoorlist, and the SV parameter is\n*cv* itself. This implements standard prototype processing. It can be changed, for a\nparticular subroutine, by \"cvsetcallchecker\".\n\nvoid cvgetcallchecker(CV *cv, Perlcallchecker *ckfunp,\nSV ckobjp)\n\ncvsetcallchecker\nSets the function that will be used to fix up a call to *cv*. Specifically, the function is\napplied to an \"entersub\" op tree for a subroutine call, not marked with \"&\", where the\ncallee can be identified at compile time as *cv*.\n\nThe C-level function pointer is supplied in *ckfun*, and an SV argument for it is supplied\nin *ckobj*. The function is intended to be called in this manner:\n\nentersubop = ckfun(aTHX entersubop, namegv, ckobj);\n\nIn this call, *entersubop* is a pointer to the \"entersub\" op, which may be replaced by the\ncheck function, and *namegv* is a GV supplying the name that should be used by the check\nfunction to refer to the callee of the \"entersub\" op if it needs to emit any diagnostics. It\nis permitted to apply the check function in non-standard situations, such as to a call to a\ndifferent subroutine or to a method call.\n\nThe current setting for a particular CV can be retrieved by \"cvgetcallchecker\".\n\nvoid cvsetcallchecker(CV *cv, Perlcallchecker ckfun,\nSV *ckobj)\n\nckentersubargslist\nPerforms the default fixup of the arguments part of an \"entersub\" op tree. This consists of\napplying list context to each of the argument ops. This is the standard treatment used on a\ncall marked with \"&\", or a method call, or a call through a subroutine reference, or any\nother call where the callee can't be identified at compile time, or a call where the callee\nhas no prototype.\n\nOP *ckentersubargslist(OP *entersubop)\n\nckentersubargsproto\nPerforms the fixup of the arguments part of an \"entersub\" op tree based on a subroutine\nprototype. This makes various modifications to the argument ops, from applying context up to\ninserting \"refgen\" ops, and checking the number and syntactic types of arguments, as\ndirected by the prototype. This is the standard treatment used on a subroutine call, not\nmarked with \"&\", where the callee can be identified at compile time and has a prototype.\n\n*protosv* supplies the subroutine prototype to be applied to the call. It may be a normal\ndefined scalar, of which the string value will be used. Alternatively, for convenience, it\nmay be a subroutine object (a \"CV*\" that has been cast to \"SV*\") which has a prototype. The\nprototype supplied, in whichever form, does not need to match the actual callee referenced\nby the op tree.\n\nIf the argument ops disagree with the prototype, for example by having an unacceptable\nnumber of arguments, a valid op tree is returned anyway. The error is reflected in the\nparser state, normally resulting in a single exception at the top level of parsing which\ncovers all the compilation errors that occurred. In the error message, the callee is\nreferred to by the name defined by the *namegv* parameter.\n\nOP *ckentersubargsproto(OP *entersubop, GV *namegv,\nSV *protosv)\n\nckentersubargsprotoorlist\nPerforms the fixup of the arguments part of an \"entersub\" op tree either based on a\nsubroutine prototype or using default list-context processing. This is the standard\ntreatment used on a subroutine call, not marked with \"&\", where the callee can be identified\nat compile time.\n\n*protosv* supplies the subroutine prototype to be applied to the call, or indicates that\nthere is no prototype. It may be a normal scalar, in which case if it is defined then the\nstring value will be used as a prototype, and if it is undefined then there is no prototype.\nAlternatively, for convenience, it may be a subroutine object (a \"CV*\" that has been cast to\n\"SV*\"), of which the prototype will be used if it has one. The prototype (or lack thereof)\nsupplied, in whichever form, does not need to match the actual callee referenced by the op\ntree.\n\nIf the argument ops disagree with the prototype, for example by having an unacceptable\nnumber of arguments, a valid op tree is returned anyway. The error is reflected in the\nparser state, normally resulting in a single exception at the top level of parsing which\ncovers all the compilation errors that occurred. In the error message, the callee is\nreferred to by the name defined by the *namegv* parameter.\n\nOP *ckentersubargsprotoorlist(OP *entersubop, GV *namegv,\nSV *protosv)\n", "subsections": [] }, "SEE ALSO": { "content": "B::CallChecker, Devel::CallParser, \"cvsetcallchecker\" in perlapi\n", "subsections": [] }, "AUTHOR": { "content": "Andrew Main (Zefram) \n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 2011, 2012, 2013, 2015, 2017 Andrew Main (Zefram) \n", "subsections": [] }, "LICENSE": { "content": "This module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } } } }