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;

    # fork child worker processes and exit when parent is finished
    #   returns opts for worker processes and undef for parent process
    $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

This module can be used in a script to concurrently process a --batch list of command option lines.

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

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

This module allows you to process a list of option command lines, 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.

The --batch list lines are processed one at a time unless linux /proc/stat is detected, in which case list command lines are processed concurrently as fast as possible without overutilizing the cpu.

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

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

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 options hash ref containing at least a batch setting key.

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;

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