File Coverage

blib/lib/Beam/Minion.pm

Criterion	Covered	Total	%
statement	15	20	75.0
branch			n/a
condition			n/a
subroutine	5	6	83.3
pod	2	2	100.0
total	22	28	78.5

package Beam::Minion;
our $VERSION = '0.019';
# ABSTRACT: A distributed task runner for Beam::Wire containers

#pod =head1 SYNOPSIS
#pod
#pod     # Command-line interface
#pod     export BEAM_MINION=sqlite://test.db            # Configure a DSN directly
#pod     export BEAM_MINION=file:///etc/beam/minion.yml # Configuration file
#pod     beam minion worker
#pod     beam minion run   [...]
#pod     beam minion help
#pod
#pod     # Perl interface
#pod     Beam::Minion->init(%config)
#pod     Beam::Minion->enqueue( $container, $service, \@args, \%opt );
#pod
#pod =head1 DESCRIPTION
#pod
#pod L is a distributed task runner. One or more workers are
#pod created to run tasks, and then each task is sent to a worker to be run.
#pod Tasks are configured as L objects by L
#pod container files.
#pod
#pod =head1 GETTING STARTED
#pod
#pod =head2 Configure Minion
#pod
#pod To start running your L jobs, you must first start
#pod a L worker with the L
#pod worker.command|Beam::Minion::Command::worker>.  Minion requires
#pod a database to coordinate workers, and communicates with this database
#pod using a L.
#pod
#pod The supported Minion backends are:
#pod
#pod =over
#pod
#pod =item *
#pod
#pod L - C<< sqlite: >>
#pod
#pod =item *
#pod
#pod L - C<< postgresql://:@/ >>
#pod
#pod =item *
#pod
#pod L - C<< mysql://:@/ >>
#pod
#pod =item *
#pod
#pod L - C<< mongodb://: >>
#pod
#pod =back
#pod
#pod Minion will automatically deploy the
#pod database tables it needs, so be sure to allow the right permissions (if
#pod the database has such things).
#pod
#pod In order to communicate with Minion workers on other machines, it will
#pod be necessary to use a database accessible from the network (so, not
#pod SQLite).
#pod
#pod =head3 Environment variable
#pod
#pod Once you've picked a database backend, configure the C
#pod environment variable with the URL. This could leave the password in the environment variable
#pod which could leak out.
#pod
#pod =head3 Configuration File
#pod
#pod To read configuration from a file, set the C environment variable
#pod to a URL starting with C and then a path to a YAML file containing a
#pod hash of the configuration passed to L.
#pod
#pod =head2 Start a Worker
#pod
#pod Once the C environment variable is set, you can start
#pod a worker with C<< beam minion worker >>. Each worker can run jobs from
#pod all the containers it can find from the C environment
#pod variable. Each worker will run up to 4 jobs concurrently.
#pod
#pod =head2 Spawn a Job
#pod
#pod Jobs are spawned with C<< beam minion run   >>.
#pod The C must be an object that consumes the L
#pod role. C should be a path to a container file and can be
#pod an absolute path, a path relative to the current directory, or a
#pod path relative to one of the paths in the C environment
#pod variable (separated by C<:>).
#pod
#pod You can queue up jobs before you have workers running. As soon as
#pod a worker is available, it will start running jobs from the queue.
#pod
#pod =head1 SEE ALSO
#pod
#pod L, L, L
#pod
#pod =cut

use strict;
use warnings;
use Mojo::Base -strict, -signatures;
use Beam::Minion::Util qw( minion minion_init_args );

#pod =sub init
#pod
#pod   Beam::Minion->init(%config)
#pod
#pod Set the configuration for Beam::Minion. This overrides the C environment
#pod variable to allow setting configuration from any kind of source. The configuration should
#pod be a hash with a single key for the L backend to use, and a value to be
#pod passed to that backend's constructor (same as the arguments to L).
#pod
#pod =cut

sub init ($class, %config) {
  minion_init_args(%config);
}

#pod =sub enqueue
#pod
#pod     Beam::Minion->enqueue( $container_name, $task_name, \@args, \%opt );
#pod
#pod Enqueue the task named C<$task_name> from the container named C<$container_name>.
#pod The C environment variable must be set.
#pod
#pod C<\%opt> is a hash reference with the following keys:
#pod
#pod =over
#pod
#pod =item attempts
#pod
#pod Number of times to retry this job if it fails. Defaults to C<1>.
#pod
#pod =item delay
#pod
#pod Time (in seconds) to delay this job (from now). Defaults to C<0>.
#pod
#pod =item priority
#pod
#pod The job priority. Higher priority jobs get performed first. Defaults to C<0>.
#pod
#pod =back
#pod
#pod (These are the same options allowed in L
#pod method|http://mojolicious.org/perldoc/Minion#enqueue1>)
#pod
#pod =cut

sub enqueue {
    my ( $class, $container, $task, $args, $opt ) = @_;
    my $minion = minion();
    $minion->enqueue( "$container:$task", $args, $opt );
}

1;

__END__