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-0.1.0
River stage zero No dependents
/ POE::Wheel::Run::DaemonHelper

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:

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