NAME

Sub::Deferrable - Optionally queue sub invocations for later.

VERSION

Version 0.05

SYNOPSIS

    use Sub::Deferrable;
    my $queue = Sub::Deferrable->new();
    my $sub  = $queue->make_deferrable( \&some_sub );
    $sub->(@args);              # Executes immediately
    $queue->defer;
    $sub->(@more_args);         # Not executed
    $sub->(@yet_more_args);     # Not executed
    $queue->undefer;            # Both calls now executed synchronously;
                                # subsequent calls execute immediately.

Sub::Deferrable provides methods for wrapping a sub reference, giving it a split personality. In "normal" mode the wrapper simply calls the sub, passing along any arguments. In "deferred" mode, the wrapper creates an invocation object and saves it on a queue. When the queue is returned to "normal" mode, all invocations on the queue are executed immediately.

EXPORT

No exports.

METHODS

new

Returns a new Sub::Deferrable object with an empty queue.

$self->mk_deferrable( \&some_sub )

Returns a new sub reference, which normally behaves like \&some_sub, but which saves an invocation of \&some_sub on the queue when in "deferred" mode.

An optional extra argument provides a sub reference to be applied to the invocation arguments at queueing time. If this argument is supplied, it is probably a reference to Storable::dclone, which will create a deep copy of the arguments and so break any reference pointers. This might be needed if, say, the arguments at invocation time might change before the queued sub is run.

$self->deferring

Returns true when deferrable subs are queued; false when they are than invoked immediately.

$self->defer

Stop executing deferrable subs, and start queueing them instead. Repeated calls to $self->defer are equivalent to a single call; in particular, one call to $self->undefer will turn off deferral mode.

$self->undefer

Stop queueing subs, and start executing them immediately. Any subs already queued are executed before undefer() returns.

$self->cancel

Stop queueing subs, but discard any subs already queued.

DESTROY

On destruction, all queued subs are invoked. This is a failsafe; please do not write code that relies on this behavior. By the time this object is destroyed, it's likely too late to invoke your subs anyway, so this will probably crash your app. As you so richly deserve.

AUTHOR

Budney, Len, <Budney.Len@grantstreet.com>

BUGS

Not all subs are deferrable, by their nature. If the sub interacts with an open file or socket, for example, execution may fail later because the file or socket is closed. Presumably, you thought of that before you decided to make your sub deferrable.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005-2012 Grant Street Group. All rights reserved.

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

cpanm Sub::Deferrable

perl -MCPAN -e shell
install Sub::Deferrable