NAME

Mnet::Batch - Concurrently process a list of command line options

SYNOPSIS

    # usually combined with Mnet::Opts::Cli
    use Mnet::Batch;
    use Mnet::Opts::Cli;

    # define --sample cli option
    Mnet::Opts::Cli::define({
        getopt   => "sample=s",
        help_tip => "set to input string",
    });

    # usually cli options are read before calling Mnet::Batch::fork()
    my $cli = Mnet::Opts::Cli->new;

    # read command line options, fork children if in --batch mode
    #   exit --batch parent process when finished forking children
    $cli = Mnet::Batch::fork($cli);
    exit if not $cli;

    # code below runs for batch workers and non-batch executions
    print "sample = $cli->{sample}\n";

DESCRIPTION

Mnet::Batch can be used in a script to concurrently process a --batch list of command option lines.

For example, you might run a script sequentially over and over, like this:

 script.pl --sample 1
 script.pl --sample 2a
 script.pl --sample ...

Or use Mnet::Batch which allows you to process a list of option command lines after loading the script once, like this:

 echo '
     --sample 1
     --sample 2a
     --sample ...
 ' | script.pl --batch /dev/stdin

In the above example the script accepts a --batch list of command option lines and forks a child worker process for each line in the list. The --batch list option can be set to a file, a named pipe, or /dev/stdin as above.

By default --batch list lines are processed one at a time unless linux /proc/stat is detected, in which case batch command lines are processed with as many concurrent processes as possible without overutilizing the cpu. The --batch-idle and --batch-min options can be used to adjust this.

Note that a script using this module will throw an error when it ends if the Mnet::Opts::Cli new method was used to parse command line arguments and the --batch option is set and the Mnet::Batch::fork function was never called.

Refer also to the documentation for the Mnet::Batch::fork function in this module for more information.

FUNCTIONS

Mnet::Batch implements the functions listed below.

Mnet::Batch::fork

    \%child_opts = Mnet::Batch::fork(\%opts)
    or (\%child_opts, @child_extras) = Mnet::Batch::fork(\%opts)

The Mnet::Batch::fork function requires an input opts hash ref containing at least a 'batch' key. Input can be an Mnet::Opts::Cli object.

The returned child opts hash ref will contain settings from the input opts hash overlaid with options from the current batch command options line. Extra args from batch command option lines are also returned if called in list context.

The returned child opts hash ref will be undefined for the batch parent process when the parent process is finished.

    my ($cli, @extras) = Mnet::Opts::Cli->new;
    ($cli, @extras) = Mnet::Batch::fork($cli);
    exit if not defined $cli;
    # child processing continues...

Also note that this function can be called by scripts that are not using the Mnet::Opts::Cli module to parse command line options. In this case the returned child_opts value will be a scalar containing the input batch line, as in the following example:

    ( echo "line = 1"; echo "line = 2" ) | perl -e '
        use Mnet::Batch
        my $line = Mnet::Batch::fork({ batch => "/dev/stdin" });
        exit if not defined $line;
        die "child should have line set" if $line !~ /^line =/
    '

Refer also to the SYNOPSIS section of this perldoc for more information.

SEE ALSO

Mnet

Mnet::Opts::Cli

Mnet::Opts::Set