/ 
callback-hook-0.1.0
/ callback::hook

NAME

callback::hook - unified hooks for system/module programming

SYNOPSIS

in module code that uses a callback, just define subroutines that start "hook_"

package my_foo_module;
use callback::hook;
sub hook_after_foo{
   print "foo phase is complete, after_foo hook got args: @_\n";
};

in system code that calls callbacks, find them in the callback::hook name space.

 package mainfoo;
 ...
    callback::hook::before_foo($this);
    $this->do_the_foo;
    callback::hook::after_foo($this);

DESCRIPTION

Another in a continuing series of short, subtle CPAN modules, callback::hook provides a standard interface for writing routines that will get called at defined times in the processing internal to a system, and a standard way for calling the routines at those defined times.

defining hook_* subroutines

Right before beginning run-time, all packages that use callback::hook are scanned for subroutines with names matching /hook_(.+)/ and any such subroutines are pushed onto @{"callback::hook::$1"} arrays.

calling hooks

When code calls callback::hook::NAME, all subroutines in @callback::hook::NAME are executed, in array context, and the results of each are stored in %callback::hook::results under the coderef as a key.

getting hook results

you can find out the result of the last call to your package's coderef on the NAME hook by looking at the @{$callback::hook::results{\&hook_NAME}} array.

EXPORT

None. This module imports coderefs from the callers space and lists them in arrays in its own space, rather than exporting anything.

arguable bug and two workarounds for it

Only one subroutine per callback-name per package. So if you need to create multiple callbacks on the same hook, either directly manipulate the @callback::hook::NAME array for your callback's name, or declare each callback function in its own package, that all use callback::hook.

HISTORY

0.1.0

Written after reading about automatic callback discovery on the qpsmtpd mailing list, in response to a request from Tim Bunce, for possible use with DBI.

SEE ALSO

please use rt.cpan.org for bug reports and feedback.

AUTHOR

David Nicol <davidnico@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by David Nicol

Released under GNU Public License version 2. The author does not believe that linking in a library for use constitutes creation of a derivative work.