|
Packit |
b3426c |
=head1 NAME
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Devel::CallChecker - custom op checking attached to subroutines
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 SYNOPSIS
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
# to generate header prior to XS compilation
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
perl -MDevel::CallChecker=callchecker0_h \
|
|
Packit |
b3426c |
-e 'print callchecker0_h' > callchecker0.h
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
# in Perl part of module
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
use Devel::CallChecker;
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
/* in XS */
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
#include "callchecker0.h"
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
cv_get_call_checker(cv, &ckfun, &ckobj);
|
|
Packit |
b3426c |
static OP *my_ckfun(pTHX_ OP *o, GV *namegv, SV *ckobj);
|
|
Packit |
b3426c |
cv_set_call_checker(cv, my_ckfun, ckobj);
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 DESCRIPTION
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
This module makes some new features of the Perl 5.14.0 C API available
|
|
Packit |
b3426c |
to XS modules running on older versions of Perl. The features are
|
|
Packit |
b3426c |
centred around the function C<cv_set_call_checker>, which allows XS
|
|
Packit |
b3426c |
code to attach a magical annotation to a Perl subroutine, resulting in
|
|
Packit |
b3426c |
resolvable calls to that subroutine being mutated at compile time by
|
|
Packit |
b3426c |
arbitrary C code. This module makes C<cv_set_call_checker> and several
|
|
Packit |
b3426c |
supporting functions available. (It is possible to achieve the effect
|
|
Packit |
b3426c |
of C<cv_set_call_checker> from XS code on much earlier Perl versions,
|
|
Packit |
b3426c |
but it is painful to achieve without the centralised facility.)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
This module provides the implementation of the functions at runtime (on
|
|
Packit |
b3426c |
Perls where they are not provided by the core). It also, at compile time,
|
|
Packit |
b3426c |
supplies the C header file and link library which provide access to the
|
|
Packit |
b3426c |
functions. In normal use, L</callchecker0_h> and L</callchecker_linkable>
|
|
Packit |
b3426c |
should be called at build time (not authoring time) for the module that
|
|
Packit |
b3426c |
wishes to use the C functions.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=cut
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
package Devel::CallChecker;
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
{ use 5.006; }
|
|
Packit |
b3426c |
use warnings;
|
|
Packit |
b3426c |
use strict;
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
our $VERSION = "0.008";
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
use parent "Exporter";
|
|
Packit |
b3426c |
our @EXPORT_OK = qw(callchecker0_h callchecker_linkable);
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
{
|
|
Packit |
b3426c |
require DynaLoader;
|
|
Packit |
b3426c |
local our @ISA = qw(DynaLoader);
|
|
Packit |
b3426c |
local *dl_load_flags = sub { 1 };
|
|
Packit |
b3426c |
__PACKAGE__->bootstrap($VERSION);
|
|
Packit |
b3426c |
}
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 CONSTANTS
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=over
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item callchecker0_h
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Content of a C header file, intended to be named "C<callchecker0.h>".
|
|
Packit |
b3426c |
It is to be included in XS code, and C<perl.h> must be included first.
|
|
Packit |
b3426c |
When the XS module is loaded at runtime, the C<Devel::CallChecker>
|
|
Packit |
b3426c |
module must be loaded first. This will result in the Perl API functions
|
|
Packit |
b3426c |
C<rv2cv_op_cv>, C<ck_entersub_args_list>, C<ck_entersub_args_proto>,
|
|
Packit |
b3426c |
C<ck_entersub_args_proto_or_list>, C<cv_get_call_checker>, and
|
|
Packit |
b3426c |
C<cv_set_call_checker>, as defined below and in the Perl 5.14.0 API,
|
|
Packit |
b3426c |
being available to the XS code.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item callchecker_linkable
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
List of names of files that must be used as additional objects when
|
|
Packit |
b3426c |
linking an XS module that uses the C functions supplied by this module.
|
|
Packit |
b3426c |
This list will be empty on many platforms.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=cut
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
sub callchecker_linkable() {
|
|
Packit |
b3426c |
require DynaLoader::Functions;
|
|
Packit |
b3426c |
DynaLoader::Functions->VERSION(0.001);
|
|
Packit |
b3426c |
return DynaLoader::Functions::linkable_for_module(__PACKAGE__);
|
|
Packit |
b3426c |
}
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=back
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 C FUNCTIONS
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=over
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item rv2cv_op_cv
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Examines an op, which is expected to identify a subroutine at runtime,
|
|
Packit |
b3426c |
and attempts to determine at compile time which subroutine it identifies.
|
|
Packit |
b3426c |
This is normally used during Perl compilation to determine whether
|
|
Packit |
b3426c |
a prototype can be applied to a function call. I<cvop> is the op
|
|
Packit |
b3426c |
being considered, normally an C<rv2cv> op. A pointer to the identified
|
|
Packit |
b3426c |
subroutine is returned, if it could be determined statically, and a null
|
|
Packit |
b3426c |
pointer is returned if it was not possible to determine statically.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Whether the subroutine is statically identifiable is determined in
|
|
Packit |
b3426c |
accordance with the prevailing standards of the Perl version being used.
|
|
Packit |
b3426c |
The same criteria are used that the core uses to determine whether to
|
|
Packit |
b3426c |
apply a prototype to a subroutine call. From version 5.11.2 onwards, the
|
|
Packit |
b3426c |
subroutine can be determined if the RV that the C<rv2cv> is to operate
|
|
Packit |
b3426c |
on is provided by a suitable C<gv> or C<const> op. Prior to 5.11.2,
|
|
Packit |
b3426c |
only a C<gv> op will do. A C<gv> op is suitable if the GV's CV slot
|
|
Packit |
b3426c |
is populated. A C<const> op is suitable if the constant value must be
|
|
Packit |
b3426c |
an RV pointing to a CV. Details of this process may change in future
|
|
Packit |
b3426c |
versions of Perl.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
If the C<rv2cv> op has the C<OPpENTERSUB_AMPER> flag set then no attempt
|
|
Packit |
b3426c |
is made to identify the subroutine statically: this flag is used to
|
|
Packit |
b3426c |
suppress compile-time magic on a subroutine call, forcing it to use
|
|
Packit |
b3426c |
default runtime behaviour.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling
|
|
Packit |
b3426c |
of a GV reference is modified. If a GV was examined and its CV slot was
|
|
Packit |
b3426c |
found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set.
|
|
Packit |
b3426c |
If the op is not optimised away, and the CV slot is later populated with
|
|
Packit |
b3426c |
a subroutine having a prototype, that flag eventually triggers the warning
|
|
Packit |
b3426c |
"called too early to check prototype".
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead
|
|
Packit |
b3426c |
of returning a pointer to the subroutine it returns a pointer to the
|
|
Packit |
b3426c |
GV giving the most appropriate name for the subroutine in this context.
|
|
Packit |
b3426c |
Normally this is just the C<CvGV> of the subroutine, but for an anonymous
|
|
Packit |
b3426c |
(C<CvANON>) subroutine that is referenced through a GV it will be the
|
|
Packit |
b3426c |
referencing GV. The resulting C<GV*> is cast to C<CV*> to be returned.
|
|
Packit |
b3426c |
A null pointer is returned as usual if there is no statically-determinable
|
|
Packit |
b3426c |
subroutine.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
CV *rv2cv_op_cv(OP *cvop, U32 flags)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item cv_get_call_checker
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Retrieves the function that will be used to fix up a call to I<cv>.
|
|
Packit |
b3426c |
Specifically, the function is applied to an C<entersub> op tree for a
|
|
Packit |
b3426c |
subroutine call, not marked with C<&>, where the callee can be identified
|
|
Packit |
b3426c |
at compile time as I<cv>.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
The C-level function pointer is returned in I<*ckfun_p>, and an SV
|
|
Packit |
b3426c |
argument for it is returned in I<*ckobj_p>. The function is intended
|
|
Packit |
b3426c |
to be called in this manner:
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
In this call, I<entersubop> is a pointer to the C<entersub> op,
|
|
Packit |
b3426c |
which may be replaced by the check function, and I<namegv> is a GV
|
|
Packit |
b3426c |
supplying the name that should be used by the check function to refer
|
|
Packit |
b3426c |
to the callee of the C<entersub> op if it needs to emit any diagnostics.
|
|
Packit |
b3426c |
It is permitted to apply the check function in non-standard situations,
|
|
Packit |
b3426c |
such as to a call to a different subroutine or to a method call.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
By default, the function is
|
|
Packit |
b3426c |
L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>,
|
|
Packit |
b3426c |
and the SV parameter is I<cv> itself. This implements standard
|
|
Packit |
b3426c |
prototype processing. It can be changed, for a particular subroutine,
|
|
Packit |
b3426c |
by L</cv_set_call_checker>.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
|
|
Packit |
b3426c |
SV **ckobj_p)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item cv_set_call_checker
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Sets the function that will be used to fix up a call to I<cv>.
|
|
Packit |
b3426c |
Specifically, the function is applied to an C<entersub> op tree for a
|
|
Packit |
b3426c |
subroutine call, not marked with C<&>, where the callee can be identified
|
|
Packit |
b3426c |
at compile time as I<cv>.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
The C-level function pointer is supplied in I<ckfun>, and an SV argument
|
|
Packit |
b3426c |
for it is supplied in I<ckobj>. The function is intended to be called
|
|
Packit |
b3426c |
in this manner:
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
In this call, I<entersubop> is a pointer to the C<entersub> op,
|
|
Packit |
b3426c |
which may be replaced by the check function, and I<namegv> is a GV
|
|
Packit |
b3426c |
supplying the name that should be used by the check function to refer
|
|
Packit |
b3426c |
to the callee of the C<entersub> op if it needs to emit any diagnostics.
|
|
Packit |
b3426c |
It is permitted to apply the check function in non-standard situations,
|
|
Packit |
b3426c |
such as to a call to a different subroutine or to a method call.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
The current setting for a particular CV can be retrieved by
|
|
Packit |
b3426c |
L</cv_get_call_checker>.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
|
|
Packit |
b3426c |
SV *ckobj)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item ck_entersub_args_list
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Performs the default fixup of the arguments part of an C<entersub>
|
|
Packit |
b3426c |
op tree. This consists of applying list context to each of the
|
|
Packit |
b3426c |
argument ops. This is the standard treatment used on a call marked
|
|
Packit |
b3426c |
with C<&>, or a method call, or a call through a subroutine reference,
|
|
Packit |
b3426c |
or any other call where the callee can't be identified at compile time,
|
|
Packit |
b3426c |
or a call where the callee has no prototype.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
OP *ck_entersub_args_list(OP *entersubop)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item ck_entersub_args_proto
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Performs the fixup of the arguments part of an C<entersub> op tree
|
|
Packit |
b3426c |
based on a subroutine prototype. This makes various modifications to
|
|
Packit |
b3426c |
the argument ops, from applying context up to inserting C<refgen> ops,
|
|
Packit |
b3426c |
and checking the number and syntactic types of arguments, as directed by
|
|
Packit |
b3426c |
the prototype. This is the standard treatment used on a subroutine call,
|
|
Packit |
b3426c |
not marked with C<&>, where the callee can be identified at compile time
|
|
Packit |
b3426c |
and has a prototype.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
I<protosv> supplies the subroutine prototype to be applied to the call.
|
|
Packit |
b3426c |
It may be a normal defined scalar, of which the string value will be used.
|
|
Packit |
b3426c |
Alternatively, for convenience, it may be a subroutine object (a C<CV*>
|
|
Packit |
b3426c |
that has been cast to C<SV*>) which has a prototype. The prototype
|
|
Packit |
b3426c |
supplied, in whichever form, does not need to match the actual callee
|
|
Packit |
b3426c |
referenced by the op tree.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
If the argument ops disagree with the prototype, for example by having
|
|
Packit |
b3426c |
an unacceptable number of arguments, a valid op tree is returned anyway.
|
|
Packit |
b3426c |
The error is reflected in the parser state, normally resulting in a single
|
|
Packit |
b3426c |
exception at the top level of parsing which covers all the compilation
|
|
Packit |
b3426c |
errors that occurred. In the error message, the callee is referred to
|
|
Packit |
b3426c |
by the name defined by the I<namegv> parameter.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
|
|
Packit |
b3426c |
SV *protosv)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=item ck_entersub_args_proto_or_list
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Performs the fixup of the arguments part of an C<entersub> op tree either
|
|
Packit |
b3426c |
based on a subroutine prototype or using default list-context processing.
|
|
Packit |
b3426c |
This is the standard treatment used on a subroutine call, not marked
|
|
Packit |
b3426c |
with C<&>, where the callee can be identified at compile time.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
I<protosv> supplies the subroutine prototype to be applied to the call,
|
|
Packit |
b3426c |
or indicates that there is no prototype. It may be a normal scalar,
|
|
Packit |
b3426c |
in which case if it is defined then the string value will be used
|
|
Packit |
b3426c |
as a prototype, and if it is undefined then there is no prototype.
|
|
Packit |
b3426c |
Alternatively, for convenience, it may be a subroutine object (a C<CV*>
|
|
Packit |
b3426c |
that has been cast to C<SV*>), of which the prototype will be used if it
|
|
Packit |
b3426c |
has one. The prototype (or lack thereof) supplied, in whichever form,
|
|
Packit |
b3426c |
does not need to match the actual callee referenced by the op tree.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
If the argument ops disagree with the prototype, for example by having
|
|
Packit |
b3426c |
an unacceptable number of arguments, a valid op tree is returned anyway.
|
|
Packit |
b3426c |
The error is reflected in the parser state, normally resulting in a single
|
|
Packit |
b3426c |
exception at the top level of parsing which covers all the compilation
|
|
Packit |
b3426c |
errors that occurred. In the error message, the callee is referred to
|
|
Packit |
b3426c |
by the name defined by the I<namegv> parameter.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
|
|
Packit |
b3426c |
SV *protosv)
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=back
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 SEE ALSO
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
L<B::CallChecker>,
|
|
Packit |
b3426c |
L<Devel::CallParser>,
|
|
Packit |
b3426c |
L<perlapi/cv_set_call_checker>
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 AUTHOR
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Andrew Main (Zefram) <zefram@fysh.org>
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 COPYRIGHT
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
Copyright (C) 2011, 2012, 2013, 2015, 2017
|
|
Packit |
b3426c |
Andrew Main (Zefram) <zefram@fysh.org>
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=head1 LICENSE
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
This module is free software; you can redistribute it and/or modify it
|
|
Packit |
b3426c |
under the same terms as Perl itself.
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
=cut
|
|
Packit |
b3426c |
|
|
Packit |
b3426c |
1;
|