NAME

Test::Mock::Alarm - Mock perl's built-in alarm function

VERSION

version 0.13

SYNOPSIS

    # make this the first include
    use Test::Mock::Alarm qw(set_alarm restore_alarm);

    # trigger any alarm of 15 seconds
    set_alarm( sub { die 'alarm' if (shift == 15) } );

    # this will alarm
    foo();

    # reset it back to normal
    restore_alarm();

    # now this will not
    foo();

    # a simplified function with an alarm
    sub foo {
        eval {
            alarm(15);
            bar();     # I take less than 15 seconds
            alarm(0);
        };
        if ( $@ ) {
            print "The alarm was triggered.\n";
        }
    }

DESCRIPTION

Test::Mock::Alarm is a simple interface that lets you replace perl's built-in alarm() function with whatever you'd like, allowing you to trigger alarms to test your alarm handling code.

SUBROUTINES/METHODS

set_alarm

This will replace the built-in alarm() with whatever you'd like. Almost always, this will look something like:

    # all alarms of 60 seconds will die with 'alarm'
    set_alarm( sub { die 'alarm' if ( shift == 60 ) } );

or

    # all alarms called from within 'Module::function' will die with 'alarm' 
    set_alarm( sub { die 'alarm' if ( (caller(3))[3] eq 'Module::function' ) } );

These are just two examples but they should be able to handle most of your alarm testing.

restore_alarm

Once you've finished testing, you can return alarm() back to normal with this.

    # fascinating abuse with alarm()
    
    restore_alarm();
    
    # it's back to normal

mocked_alarm

Test::Mock::Alarm uses this to replace perl's internal alarm().

DEPENDENCIES

None

BUGS AND LIMITATIONS

Having a series of alarms with identical timeouts, like the following, is something that would be difficult to trigger with this module's current approach.

    while ($condition) {
        alarm($timeout);
        do_something();
        alarm(0);
    }

There may be bugs that exist and other alarm situations that this may not work in - so far it's managed to work where I've needed it.

AUTHOR

Jeremy Jack < jeremy@rocketscientry.com >

LICENSE AND COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.