Beam::Runnable - Role for runnable objects


version 0.016


    package My::Runnable;
    use Moo;
    with 'Beam::Runnable';
    sub run { ... }


This role declares your object as runnable by the beam run command. Runnable objects will be listed by the beam list command, and their documentation displayed by the beam help command.

The run method

The run method is the main function of your object. See below for its arguments and return value.

The run method should be as small as possible, ideally only parsing command-line arguments and delegating to other objects to do the real work. Though your runnable object can be used in other code, the API of the run method is a terrible way to do that, and it is better to keep your business logic and other important code in another class.


The beam help command will display the documentation of your module: the NAME (abstract), SYNOPSIS, DESCRIPTION, ARGUMENTS, OPTIONS, and SEE ALSO sections. This is the same as what Pod::Usage produces by default.

The beam list command, when listing runnable objects, will display either the summary attribute or the NAME POD section (abstract) next to the service name.

Additional Roles

Additional roles can add common functionality to your runnable script. Some of these are included in the Beam::Runner distribution:


This role will add a timeout using Perl's built-in alarm() function. Once the timeout is reached, the program will print a warning and exit with an error code.



A summary of the task to be run. This will be displayed by the beam list command in the list.



    my $exit_code = $obj->run( @argv );

Execute the runnable object with the given arguments and returning the exit status. @argv is passed-in from the command line and may contain options (which you can parse using Getopt::Long's GetOptionsFromArray function.


beam, Beam::Runner


Doug Bell <>


This software is copyright (c) 2016 by Doug Bell.

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