README

   1 NAME
   2     Sub::Op - Install subroutines as opcodes.
   3
   4 VERSION
   5     Version 0.02
   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.namelen = 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 namelen"
 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 CAVEATS
 150     Preexistent definitions of a sub whose name is handled by Sub::Op are
 151     restored at the end of the lexical scope in which the module is used.
 152     But if you define a sub in the scope of action of Sub::Op with a name
 153     that is currently being replaced, the new declaration will be
 154     obliterated at the scope end.
 155
 156     Function calls without parenthesis inside an "eval STRING" in the scope
 157     of the pragma won't be replaced. I know a few ways of fixing this, but
 158     I've not yet decided on which.
 159
 160 DEPENDENCIES
 161     perl 5.10.
 162
 163     Variable::Magic, B::Hooks::EndOfScope.
 164
 165     ExtUtils::Depends.
 166
 167 SEE ALSO
 168     subs::auto.
 169
 170     B::Hooks::XSUB::CallAsOp provides a C API to declare XSUBs that
 171     effectively call a specific PP function. Thus, it allows you to write
 172     XSUBs with the PP stack conventions used for implementing perl core
 173     keywords. There's no opcode replacement and no parsing hacks.
 174
 175     B::Hooks::OP::Check::EntersubForCV.
 176
 177 AUTHOR
 178     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 179
 180     You can contact me by mail or on "irc.perl.org" (vincent).
 181
 182 BUGS
 183     Please report any bugs or feature requests to "bug-sub-op at
 184     rt.cpan.org", or through the web interface at
 185     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Op>. I will be
 186     notified, and then you'll automatically be notified of progress on your
 187     bug as I make changes.
 188
 189 SUPPORT
 190     You can find documentation for this module with the perldoc command.
 191
 192         perldoc Sub::Op
 193
 194     Tests code coverage report is available at
 195     <http://www.profvince.com/perl/cover/Sub-Op>.
 196
 197 COPYRIGHT & LICENSE
 198     Copyright 2010 Vincent Pit, all rights reserved.
 199
 200     This program is free software; you can redistribute it and/or modify it
 201     under the same terms as Perl itself.
 202