/ 
Sub-Op-0.01
River stage zero No dependents
/ Sub::Op

NAME

Sub::Op - Install subroutines as opcodes.

VERSION

Version 0.01

SYNOPSIS

In your XS file :

#include "sub_op.h"

STATIC OP *scalar_util_reftype(pTHX) {
 dSP;
 dMARK;
 SV *sv = POPs;
 if (SvMAGICAL(sv))
  mg_get(sv);
 if (SvROK(sv))
  PUSHs(sv_reftype(SvRV(sv), 0));
 else
  PUSHs(&PL_sv_undef);
 RETURN;
}

MODULE = Scalar::Util::Ops       PACKAGE = Scalar::Util::Ops

BOOT:
{
 sub_op_config_t c;
 c.name  = "reftype";
 c.len   = sizeof("reftype")-1;
 c.pp    = scalar_util_reftype;
 c.check = 0;
 c.ud    = NULL;
 sub_op_register(aTHX_ &c);
}

In your Perl module file :

package Scalar::Util::Ops;

use strict;
use warnings;

our ($VERSION, @ISA);

use Sub::Op; # Before loading our own shared library

BEGIN {
 $VERSION = '0.01';
 require DynaLoader;
 push @ISA, 'DynaLoader';
 __PACKAGE__->bootstrap($VERSION);
}

sub import   { Sub::Op::enable(reftype => scalar caller) }

sub unimport { Sub::Op::disable(reftype => scalar caller) }

1;

In your Makefile.PL :

use ExtUtils::Depends;

my $ed = ExtUtils::Depends->new('Scalar::Util::Ops' => 'Sub::Op');

WriteMakefile(
 $ed->get_makefile_vars,
 ...
);

DESCRIPTION

This module provides a C and Perl API for replacing subroutine calls by custom opcodes. This has two main advantages :

  • it gets rid of the overhead of a normal subroutine call ;

  • there's no symbol table entry defined for the subroutine.

Subroutine calls with and without parenthesis are handled. Ampersand calls are not replaced, and as such will still allow to call a subroutine with same name defined earlier. This may or may not be considered as a bug, but it gives the same semantics as Perl keywords, so I believe it's reasonable.

When B and B::Deparse are loaded, they get automatically monkeypatched so that introspecting modules like B::Concise and B::Deparse still produce a valid output.

C API

sub_op_config_t

A typedef'd struct that configures how Sub::Op should handle a given subroutine name. It has the following members :

  • const char *name

    The name of the subroutine you want to replace. Allowed to be static.

  • STRLEN len

    name's length, in bytes.

  • Perl_ppaddr_t pp

    The pp function that will be called instead of the subroutine. Perl_ppaddr_t is a typedef'd function pointer defined by perl as :

    typedef OP *(*Perl_ppaddr_t)(pTHX);

  • sub_op_check_t check

    An optional callback that will be called each time a call to name is replaced. You can use it to attach extra info to those ops (e.g. with a pointer table) or to perform more optimizations to the optree. sub_op_check_t is a typedef'd function pointer defined by :

    typedef OP *(*sub_op_check_t)(pTHX_ OP *, void *);

  • void *ud

    An optional user data passed to the check callback.

void sub_op_register(pTHX_ const sub_op_config_t *c)

Registers a name and its configuration into Sub::Op. The caller is responsible for allocating and freeing the sub_op_config_t object. No pointer to it or to its members is kept.

PERL API

enable $name, [ $pkg ]

Enable the replacement with a custom opcode of calls to the $name subroutine of the $pkg package in the current lexical scope. A pp callback must have been registered for $name by calling the C function sub_op_register in the XS section of your module.

When $pkg is not set, it defaults to the caller package.

disable $name, [ $pkg ]

Disable the replacement for calls to $name in the package $pkg.

When $pkg is not set, it defaults to the caller package.

EXAMPLES

See the t/Sub-Op-LexicalSub directory that implements a complete example.

DEPENDENCIES

perl 5.10.

Variable::Magic, B::Hooks::EndOfScope.

ExtUtils::Depends.

SEE ALSO

subs::auto.

B::Hooks::OP::Check::EntersubForCV.

AUTHOR

Vincent Pit, <perl at profvince.com>, http://www.profvince.com.

You can contact me by mail or on irc.perl.org (vincent).

BUGS

Please report any bugs or feature requests to bug-sub-op at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Op. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Sub::Op

Tests code coverage report is available at http://www.profvince.com/perl/cover/Sub-Op.

COPYRIGHT & LICENSE

Copyright 2010 Vincent Pit, all rights reserved.

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