NAME

Devel::TraceLoad::Hook - Install a hook function to be called for each require.

VERSION

This document describes Devel::TraceLoad::Hook version 0.9.0

SYNOPSIS

register_require_hook( sub {
    my ( $when, $depth, $arg, $p, $f, $l, $rc, $err ) = @_;
    # ... do stuff ...
} ); 

DESCRIPTION

Allows hook functions that will be called before and after each require (and use) to be registered.

INTERFACE

register_require_hook

Register a function to be called immediately before and after each require (and use).

The registered function should look something like this:

sub done_require {
    my ( $when, $depth, $arg, $p, $f, $l, $rc, $err ) = @_;
    # ... do stuff ...
}

The arguments are as follows:

$when

The hook function is called both before and after the require is executed. The first argument will contain either 'before' or 'after' as appropriate.

$depth

How deeply nested this require is.

$arg

The argument to require.

$p, $f, $l

The package, file and line where the calling require or use is.

$rc, $err

When the hook function is called after a require $rc and $err will contain the return value of the require and any error that it raised.

You may throw an error (using die) from the hook function. If an error is thrown during 'before' processing the real call to require will not take place. In this way it is possible to simulate a module being unavailable.

See Devel::TraceLoad for a complete example of this interface.

CONFIGURATION AND ENVIRONMENT

Devel::TraceLoad::Hook requires no configuration files or environment variables.

DEPENDENCIES

YAML is required for yaml output.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-devel-traceload@rt.cpan.org>, or through the web interface at http://rt.cpan.org.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Andy Armstrong <andy@hexten.net>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.