NAME
POE::Wheel::Run::DaemonHelper - Helper for the POE::Wheel::Run for easy controlling logging of stdout/err as well as restarting with backoff.
VERSION
Version 0.1.0
SYNOPSIS
use strict;
use warnings;
use POE::Wheel::Run::DaemonHelper;
use POE;
my $program = 'sleep 1; echo test; derp derp derp';
my $dh = POE::Wheel::Run::DaemonHelper->new(
program => $program,
status_syslog => 1,
restart_ctl => 1,
status_print => 1,
status_print_warn => 1,
# this one will be ignored as it will already be warning for print
status_syslog_warn => 1,
);
$dh->create_session;
POE::Kernel->run();
METHODS
new
Required args as below.
- program :: The program to execute. Either a string or array.
Default :: undef
- restart_ctl :: Control if it will be restarted if it dies.
Default :: 1
Optional args are as below.
- syslog_name :: The name to use when sending stuff to syslog.
Default :: DaemonHelper
- pid_file :: The file to check for additional PIDs. Used for for
with the $dh->pids and $dh->pid_from_pid_file.
Default :: undef
- default_kill_signal :: The default signal to use for kill.
Default :: TERM
The following optional args control the backoff. Backoff is handled by Algorithm::Backoff::Exponential with consider_actual_delay and delay_on_success set to true. The following are passed to it.
- max_delay :: Max backoff delay in seconds when a program exits quickly.
Default :: 90
- initial_delay :: Initial backoff amount.
Default :: 2
The following optional args control the how the log_message method behaves.
- syslog_facility :: The syslog facility to log to.
Default :: daemon
- stdout_prepend :: What to prepend to STDOUT lines sent for status logging.
Default :: Out:
- stderr_prepend :: What to prepend to STDERR lines sent to status logging.
Default :: Err:
- status_print :: Print statuses messages to stdout.
Default :: 0
- status_print_warn :: For when error is true, use warn.
Default :: 0
- status_syslog :: Send status messages to syslog
Default :: 1
- status_syslog_warn :: Warn for error messages going to syslog. Warn will only be used once.
Default :: 0
create_session
This creates the new POE session that will handle this.
$dh->create_session;
log_message
Logs a message. Printing to stdout or sending to syslog is controlled via the status_syslog and status_print values passed to new.
- status :: What to log.
Default :: undef
- error :: If true, this will set the log level from info to err.
Default :: 0
kill
Sends the specified signal to the PIDs.
Returns undef if there are no PIDs, meaning it is not running.
If the signal is not supported, the error 5, killFailed, is set.
For understanding the return value, see the docs for the Perl function kill.
If you want to see the available signals, check Config and $Config{sig_name}.
- signal :: The signal to send. The default is conntrolled
by the setting of the default_kill_signal setting.
# send the default signal
my $count=$dh->kill;
# send the KILL signal
my $count;
eval{ $count=$dh->kill(signal=>'KILL'); };
if ($@ && $Error::Helper::errorFlag eq 'killFailed') {
die('Unkown kill signal used');
} elsif ($@) {
die($@);
} elsif ( $count < 1 ) {
die('Failed to kill any of the procs');
}
print $count . " procs signaled\n";
pid
Returns the PID of the process or undef if it has not been started.
This just return the child PID. Will not return the PID from the PID file if one is set.
my $pid = $dh->pid;
if ($pid){
print 'PID is '.$started_at."\n";
}
pids
Returns the child PID and PID from the PID file if one is specified.
This calls pid_from_pid_file via eval and ignores if it fails. If you want to check to see if that errored or not, check to see if error 4, readPidFileFailed, was set or use both pid and pid_from_pid_file.
my @pids = $dh->pids;
print 'PIDs are ' . join(', ', @pids) . "\n";
pid_from_pid_file
Reads the PID from the PID file.
If one was not specified or the file does not exist, it returns undef.
Will throw error 4, readPidFileFailed, if it could not read it.
After reading it, it will return the first integer.
my $pid;
eval{ $pid = $dh->pid_from_pid_file; };
if ($@) {
print "Could not read PID file\n";
} elsif (defined ($pid)) {
print 'PID: ' . $pid . "\n";
}
restart_ctl
Controls if the process will be restarted when it exits or not.
- restart_ctl :: A Perl boolean that if true the process will
be restarted when it exits.
Default :: undef
# next time it exits, it won't be restarted
$dh->restart_ctl(restart_ctl=>0);
If restart_ctl is undef, the current value is returned.
my $restart_ctl = $dh->restart_ctl;
if ($restart_ctl) {
print "Will be restarted when it dies.\n";
} else {
print "Will NOT be restarted when it dies.\n";
}
started
Returns a Perl boolean for if it has been started or not.
my $started=$dh->started;
if ($started){
print 'started as '.$dh->pid."\n";
}
started_at
Returns the unix time it was (re)started at or undef if it has not been started.
my $started_at = $dh->started;
if ($started_at){
print 'started at '.$started_at."\n";
}
ERROR CODES / FLAGS
1, invalidProgram
No program is specified.
2, optsBadRef
The opts has a invlaid ref.
3, optsNotInt
The opts in question should be a int.
4, readPidFileFailed
Failed to read the PID file.
5, killFailed
Failed to run kill. This in general means a improper signal was specified.
If you want to see the available signals, check Config and $Config{sig_name}.
AUTHOR
Zane C. Bowers-Hadley, <vvelox at vvelox.net>
BUGS
Please report any bugs or feature requests to bug-poe-wheel-run-daemonhelper at rt.cpan.org
, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Wheel-Run-DaemonHelper. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc POE::Wheel::Run::DaemonHelper
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Wheel-Run-DaemonHelper
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
This software is Copyright (c) 2024 by Zane C. Bowers-Hadley.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999