The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


POE::Wheel::Run::DaemonHelper - Helper for the POE::Wheel::Run for easy controlling logging of stdout/err as well as restarting with backoff.


Version 0.1.0


    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,





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


This creates the new POE session that will handle this.



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


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 ($@) {
    } elsif ( $count < 1 ) {
        die('Failed to kill any of the procs');
    print $count . " procs signaled\n";


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";


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";


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";


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

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";


Returns a Perl boolean for if it has been started or not.

    my $started=$dh->started;
    if ($started){
        print 'started as '.$dh->pid."\n";


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";


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}.


Zane C. Bowers-Hadley, <vvelox at>


Please report any bugs or feature requests to bug-poe-wheel-run-daemonhelper at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc POE::Wheel::Run::DaemonHelper

You can also look for information at:



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