/ 
Data-Tools-1.52
/ Data::Tools::Process

NAME

Data::Tools::Process provides set of functions for process control,
forking, daemonizing and pid files handling.

SYNOPSIS

use Data::Tools::Process qw( :all );  # import all functions
use Data::Tools::Process;             # the same as :all :)
use Data::Tools::Process qw( :none ); # do not import anything

# --------------------------------------------------------------------------

# fork and exec a command, returns the child pid to the parent
my $pid = fork_exec_cmd( "/usr/bin/somecmd --with args" );
waitpid( $pid, 0 );

# --------------------------------------------------------------------------

# detach from the controlling terminal and become a daemon
daemonize();
daemonize( CHDIR => '/var/lib/myapp', UMASK => 0022 );

# --------------------------------------------------------------------------

# create a pid file, holding the pid of the current process
my $res = pidfile_create( '/var/run/myapp.pid' );
die "already running with pid [$res]" if $res;

# ...and take over the pid file if the process in it is gone
my $res = pidfile_create( '/var/run/myapp.pid', STALE_CHECK => 1 );

# signal the process named in a pid file and remove the file
pidfile_kill_and_remove( '/var/run/myapp.pid' );          # sends TERM
pidfile_kill_and_remove( '/var/run/myapp.pid', 15, '5s', 9 );

# just remove the pid file
pidfile_remove( '/var/run/myapp.pid' );

# --------------------------------------------------------------------------

FUNCTIONS

fork_exec_cmd( $command )

Forks and exec()s $command in the child process.

Returns:

* the child process pid in the parent process
* undef if fork() failed

The child never returns. $command is passed to exec() as a single string, so it is subject to the usual shell handling of exec().

daemonize( %options )

Detaches the current process from the controlling terminal and turns it into a daemon: forks, calls POSIX::setsid(), forks again (SVR4 second fork policy), changes the current directory, closes all open file descriptors and reopens STDIN, STDOUT and STDERR to /dev/null.

Options are:

CHDIR => $path   # directory to change to, default is '/'
UMASK => $umask  # umask to set, default is 0077

Returns 1 in the resulting daemon process. The original process and the intermediate one exit() and never return. Dies on any of the steps failing.

NOTE: all open file descriptors are closed, including any files, sockets
      or database handles opened before the call.

pidfile_create( $pid_file_name, %options )

Creates $pid_file_name and writes the pid of the current process in it. The file is created with O_EXCL, so two processes racing for the same pid file cannot both succeed. Missing directories on the way are created.

Options are:

STALE_CHECK => 1  # take over the pid file if its process is not running

Returns:

* undef on success, the pid file now holds our pid
* a positive pid if the pid file exists and holds a running process
* -1 if the pid file cannot be created

A pid file which does not hold a valid (positive) pid is always considered stale and is replaced, regardless of STALE_CHECK.

pidfile_kill_and_remove( $pid_file_name, @signal_list )

Sends the given signals to the pid found in $pid_file_name and then removes the file. @signal_list defaults to a single TERM (15).

A list item ending with 's' is not a signal but a sleep time in seconds. All items are processed in the given order, so:

pidfile_kill_and_remove( $fname, 15, '5s', 15, '2s', 9 );

sends TERM, waits 5 seconds, sends TERM again, waits 2 seconds, sends KILL.

Returns:

* undef if $pid_file_name does not exist
* 1 if the signals have been sent and the pid file removed

pidfile_remove( $pid_file_name )

Removes $pid_file_name. Returns undef.

REQUIRED MODULES

Data::Tools::Process uses:

* POSIX
* Data::Tools

GITHUB REPOSITORY

git@github.com:cade-vs/perl-data-tools.git

git clone git://github.com/cade-vs/perl-data-tools.git

AUTHOR

Vladi Belperchinov-Shabanski "Cade"
      <cade@noxrun.com> <cade@bis.bg> <cade@cpan.org>
http://cade.noxrun.com/