view release on metacpan or  search on metacpan

Daemon.pm  view on Meta::CPAN

=item *

detects if another instance is already running and ends itself 
automatically in this case.

=item *

shows with the 'status' command if an instance is already running
and which PID it has:

    ./my-app status
    Pid file:    ./tt.pid
    Pid in file: 14914
    Running:     no
    Name match:  0

=back

=head2 Actions

C<App::Daemon> recognizes three different actions:

=over 4

=item my-app start

will start up the daemon. "start" itself is optional, as this is the 
default action, 
        
        $ ./my-app
        $
        
will also run the 'start' action. By default, it will create a pid file
and a log file in the current directory
(named C<my-app.pid> and C<my-app.log>. To change these locations, see
the C<-l> and C<-p> options.

If the -X option is given, the program
is running in foreground mode for testing purposes:

        $ ./my-app -X
        ...

=item stop

will find the daemon's PID in the pidfile and send it a SIGTERM signal. It
will verify $App::Daemon::kill_retries times if the process is still alive,
with 1-second sleeps in between.

To have App::Daemon send a different signal than SIGTERM (e.g., SIGINT), set

    use POSIX;
    $App::Daemon::kill_sig = SIGINT;

Note that his requires the numerial value (SIGINT via POSIX.pm), not a
string like "SIGINT".

=item status

will print out diagnostics on what the status of the daemon is. Typically,
the output looks like this:

    Pid file:    ./tt.pid
    Pid in file: 15562
    Running:     yes
    Name match:  1
        /usr/local/bin/perl -w test.pl

This indicates that the pidfile says that the daemon has PID 15562 and
that a process with this PID is actually running at this moment. Also,
a name grep on the process name in the process table results in 1 match,
according to the output above.

Note that the name match is unreliable, as it just looks for a command line
that looks approximately like the script itself. So if the script is
C<test.pl>, it will match lines like "perl -w test.pl" or 
"perl test.pl start", but unfortunately also lines like 
"vi test.pl".

If the process is no longer running, the status output might look like
this instead:

    Pid file:    ./tt.pid
    Pid in file: 14914
    Running:     no
    Name match:  0

The status commands exit code complies with 

    http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html

and returns

    0: if the process is up and running
    1: the process is dead but the pid file still exists
    3: the process is not running

These constants are defined within App::Daemon to help writing test
scripts:

    use constant LSB_OK               => 0;
    use constant LSB_DEAD_PID_EXISTS  => 1;
    use constant LSB_DEAD_LOCK_EXISTS => 2;
    use constant LSB_NOT_RUNNING      => 3;
    use constant LSB_UNKNOWN          => 4;
    use constant ALREADY_RUNNING      => 150;

=back

=head2 Command Line Options

=over 4

=item -X

Foreground mode. Log messages go to the screen.

=item -l logfile

Logfile to send Log4perl messages to in background mode. Defaults
to C<./[appname].log>. Note that having a logfile in the current directory
doesn't make sense except for testing environments, make sure to set this
to somewhere within C</var/log> for production use.

=item -u as_user

User to run as if started as root. Defaults to 'nobody'.

=item -g as_group

Group to run as if started as root.  Defaults to 'nogroup'.

=item -l4p l4p.conf

Path to Log4perl configuration file. Note that in this case the -v option