NAME

MCE::Signal - Temporary directory creation/cleanup & signal handling

VERSION

This document describes MCE::Signal version 1.499_004

SYNOPSIS

use MCE::Signal qw( [-keep_tmp_dir] [-use_dev_shm] );

use MCE;   ## MCE loads MCE::Signal when not present.
           ## Include MCE::Signal first for options to take effect.

DESCRIPTION

This package configures $SIG{HUP,INT,PIPE,QUIT,TERM,XCPU,XFSZ} to point to stop_and_exit and creates a temporary directory. The main process and workers receiving said signals call stop_and_exit, which signals all workers to terminate, removes the temporary directory unless -keep_tmp_dir is specified, and terminates itself.

The location of temp dir resides under $ENV{TEMP} if defined, otherwise /dev/shm if writeable and -use_dev_shm is specified, or /tmp.

The temp dir resides under $ENV{TEMP}/mce/ for native Perl on Microsoft Windows.

As of MCE 1.405, MCE::Signal no longer calls setpgrp by default. Pass the -setpgrp option to MCE::Signal to call setpgrp.

## Running MCE through Daemon::Control requires setpgrp to be called.

use MCE::Signal qw(-setpgrp);
use MCE;

The following are available arguments and their meanings.

-keep_tmp_dir     - The temporary directory is not removed during exiting
                    A message is displayed with the location afterwards

-use_dev_shm      - Create the temporary directory under /dev/shm

-no_sigmsg        - Do not display a message when receiving a signal
-no_kill9         - Do not kill -9 after receiving a signal to terminate

-setpgrp          - Calls setpgrp to set the process group for the process

                    Specify this option to ensure all workers terminate
                    when reading STDIN like so:
                       cat big_input_file | ./mce_script.pl | head -10

                    This works fine without the -setpgrp option:
                       ./mce_script.pl < big_input_file | head -10

Nothing is exported by default. Exportable are 1 variable and 2 subroutines.

$tmp_dir          - Path to the temporary directory.
stop_and_exit     - Described below
sys_cmd           - Described below

stop_and_exit ( [ $exit_status | $signal ] )

## Stops execution, removes temp directory and exits the entire
## application. Pass 'TERM' if wanting to terminate a spawned or
## running MCE state.

MCE::Signal::stop_and_exit(1);
MCE::Signal::stop_and_exit('TERM');

sys_cmd ( $command )

## Execute command and return the actual exit status. The calling
## process is also signaled if command caught SIGINT or SIGQUIT.

my $exit_status = MCE::Signal::sys_cmd($command);

EXAMPLES

## Creates tmp_dir under /tmp
use MCE::Signal;
use MCE::Signal qw( :all );

## Attempt to create tmp_dir under /dev/shm, otherwise under /tmp
use MCE::Signal qw( -use_dev_shm );

## Keep tmp_dir after script terminates
use MCE::Signal qw( -keep_tmp_dir );
use MCE::Signal qw( -use_dev_shm -keep_tmp_dir );

INDEX

MCE

AUTHOR

Mario E. Roy, <marioeroy AT gmail DOT com>

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.