README

   1 NAME
   2     Sub::Op - Install subroutines as opcodes.
   3
   4 VERSION
   5     Version 0.01
   6
   7 SYNOPSIS
   8     In your XS file :
   9
  10         #include "sub_op.h"
  11
  12         STATIC OP *scalar_util_reftype(pTHX) {
  13          dSP;
  14          dMARK;
  15          SV *sv = POPs;
  16          if (SvMAGICAL(sv))
  17           mg_get(sv);
  18          if (SvROK(sv))
  19           PUSHs(sv_reftype(SvRV(sv), 0));
  20          else
  21           PUSHs(&PL_sv_undef);
  22          RETURN;
  23         }
  24
  25         MODULE = Scalar::Util::Ops       PACKAGE = Scalar::Util::Ops
  26
  27         BOOT:
  28         {
  29          sub_op_config_t c;
  30          c.name  = "reftype";
  31          c.len   = sizeof("reftype")-1;
  32          c.pp    = scalar_util_reftype;
  33          c.check = 0;
  34          c.ud    = NULL;
  35          sub_op_register(aTHX_ &c);
  36         }
  37
  38     In your Perl module file :
  39
  40         package Scalar::Util::Ops;
  41
  42         use strict;
  43         use warnings;
  44
  45         our ($VERSION, @ISA);
  46
  47         use Sub::Op; # Before loading our own shared library
  48
  49         BEGIN {
  50          $VERSION = '0.01';
  51          require DynaLoader;
  52          push @ISA, 'DynaLoader';
  53          __PACKAGE__->bootstrap($VERSION);
  54         }
  55
  56         sub import   { Sub::Op::enable(reftype => scalar caller) }
  57
  58         sub unimport { Sub::Op::disable(reftype => scalar caller) }
  59
  60         1;
  61
  62     In your Makefile.PL :
  63
  64         use ExtUtils::Depends;
  65
  66         my $ed = ExtUtils::Depends->new('Scalar::Util::Ops' => 'Sub::Op');
  67
  68         WriteMakefile(
  69          $ed->get_makefile_vars,
  70          ...
  71         );
  72
  73 DESCRIPTION
  74     This module provides a C and Perl API for replacing subroutine calls by
  75     custom opcodes. This has two main advantages :
  76
  77     *   it gets rid of the overhead of a normal subroutine call ;
  78
  79     *   there's no symbol table entry defined for the subroutine.
  80
  81     Subroutine calls with and without parenthesis are handled. Ampersand
  82     calls are not replaced, and as such will still allow to call a
  83     subroutine with same name defined earlier. This may or may not be
  84     considered as a bug, but it gives the same semantics as Perl keywords,
  85     so I believe it's reasonable.
  86
  87     When B and B::Deparse are loaded, they get automatically monkeypatched
  88     so that introspecting modules like B::Concise and B::Deparse still
  89     produce a valid output.
  90
  91 C API
  92   "sub_op_config_t"
  93     A typedef'd struct that configures how Sub::Op should handle a given
  94     subroutine name. It has the following members :
  95
  96     *   "const char *name"
  97
  98         The name of the subroutine you want to replace. Allowed to be
  99         static.
 100
 101     *   "STRLEN len"
 102
 103         "name"'s length, in bytes.
 104
 105     *   "Perl_ppaddr_t pp"
 106
 107         The pp function that will be called instead of the subroutine.
 108         "Perl_ppaddr_t" is a typedef'd function pointer defined by perl as :
 109
 110             typedef OP *(*Perl_ppaddr_t)(pTHX);
 111
 112     *   "sub_op_check_t check"
 113
 114         An optional callback that will be called each time a call to "name"
 115         is replaced. You can use it to attach extra info to those ops (e.g.
 116         with a pointer table) or to perform more optimizations to the
 117         optree. "sub_op_check_t" is a typedef'd function pointer defined by
 118         :
 119
 120             typedef OP *(*sub_op_check_t)(pTHX_ OP *, void *);
 121
 122     *   "void *ud"
 123
 124         An optional user data passed to the "check" callback.
 125
 126   "void sub_op_register(pTHX_ const sub_op_config_t *c)"
 127     Registers a name and its configuration into Sub::Op. The caller is
 128     responsible for allocating and freeing the "sub_op_config_t" object. No
 129     pointer to it or to its members is kept.
 130
 131 PERL API
 132   "enable $name, [ $pkg ]"
 133     Enable the replacement with a custom opcode of calls to the $name
 134     subroutine of the $pkg package in the current lexical scope. A pp
 135     callback must have been registered for $name by calling the C function
 136     "sub_op_register" in the XS section of your module.
 137
 138     When $pkg is not set, it defaults to the caller package.
 139
 140   "disable $name, [ $pkg ]"
 141     Disable the replacement for calls to $name in the package $pkg.
 142
 143     When $pkg is not set, it defaults to the caller package.
 144
 145 EXAMPLES
 146     See the t/Sub-Op-LexicalSub directory that implements a complete
 147     example.
 148
 149 DEPENDENCIES
 150     perl 5.10.
 151
 152     Variable::Magic, B::Hooks::EndOfScope.
 153
 154     ExtUtils::Depends.
 155
 156 SEE ALSO
 157     subs::auto.
 158
 159     B::Hooks::OP::Check::EntersubForCV.
 160
 161 AUTHOR
 162     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 163
 164     You can contact me by mail or on "irc.perl.org" (vincent).
 165
 166 BUGS
 167     Please report any bugs or feature requests to "bug-sub-op at
 168     rt.cpan.org", or through the web interface at
 169     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Op>. I will be
 170     notified, and then you'll automatically be notified of progress on your
 171     bug as I make changes.
 172
 173 SUPPORT
 174     You can find documentation for this module with the perldoc command.
 175
 176         perldoc Sub::Op
 177
 178     Tests code coverage report is available at
 179     <http://www.profvince.com/perl/cover/Sub-Op>.
 180
 181 COPYRIGHT & LICENSE
 182     Copyright 2010 Vincent Pit, all rights reserved.
 183
 184     This program is free software; you can redistribute it and/or modify it
 185     under the same terms as Perl itself.
 186