No::Wor...PidFile(3)

🌸 NAME 🌸

No::Worries::PidFile — pid file handling without worries. This is the No::Wor...PidFile(3) page, and yep, it's User Contributed Perl Documentation, bestie. 💅

✨ SYNOPSIS ✨

Okay so here's the whole vibe in code:

         use No::Worries::PidFile qw(*);

         # idiomatic daemon code
         pf_set($pidfile);
         while (1) {
             ...
             $action = pf_check($pidfile);
             last if $action eq "quit";
             pf_touch($pidfile);
             ...
         }
         pf_unset($pidfile);

         # idiomatic daemon code with sleeping
         pf_set($pidfile);
         while (1) {
             ...
             pf_sleep($pidfile, time => 5) or last;
             ...
         }
         pf_unset($pidfile);

         # here is how to handle a --status option
         if ($Option{status}) {
             ($status, $message, $code) = pf_status($pidfile, freshness => 10);
             printf("myprog %s\n", $message);
             exit($code);
         }

         # here is how to handle a --quit option
         if ($Option{quit}) {
             pf_quit($pidfile,
                 linger   => 10,
                 callback => sub { printf("myprog %s\n", $_[0]) },
             );
         }

💖 DESCRIPTION 💖

This module eases pid file handling by providing high level functions to set, check, touch and unset pid files. All the functions die() on error. Drama, but useful drama. 😭

The pid file usually contains the process id on a single line, followed by a newline. However, it can also be followed by an optional action, also followed by a newline. This allows some kind of inter-process communication: a process using pf_quit() will append the "quit" action to the pid file and the owning process will detect this via pf_check().

All the functions properly handle concurrency. For instance, when two processes start at the exact same time and call pf_set(), only one will succeed and the other one will get an error. No cap, concurrency is handled. ✨

Careful, bestie: since an existing pid file will make pf_set() fail, it is very important to remove the pid file in all situations, including errors. The recommended way to do so is to use an END block:

         # we need to know about transient processes
         use No::Worries::Proc qw();
         # we need to record what needs to be cleaned up
         our(%NeedsCleanup);
         # we set the pid file here and remember to clean it up
         pf_set($pidfile);
         $NeedsCleanup{pidfile} = 1;
         # ... anything can happen here ...
         # cleanup code in an END block
         END {
             # transient processes do not need cleanup
             return if $No::Worries::Proc::Transient;
             # cleanup the pid file if needed
             pf_unset($pidfile) if $NeedsCleanup{pidfile};
         }

🎀 FUNCTIONS 🎀

This module provides the following functions (none of them being exported by default):

pf_set(PATH[, OPTIONS])

Set the pid file by writing the given pid at the given path; supported options:

• pid — the pid to use (default: $$)

pf_check(PATH[, OPTIONS])

Check the pid file and make sure the given pid is present, also return the action in the pid file or the empty string; supported options:

• pid — the pid to use (default: $$)

pf_unset(PATH)

Unset the pid file by removing the given path. Cleanup queen behavior. 🧚

pf_touch(PATH)

Touch the pid file (i.e. update the file modification time) to show that the owning process is alive. She's alive, bestie! 🔥

pf_sleep(PATH[, OPTIONS])

Check and touch the pid file and eventually sleep for the given amount of time, returning true if the program should continue or false if it has been told to stop via pf_quit(); supported options:

• time — the time to sleep (default: 1, can be fractional)

pf_status(PATH[, OPTIONS])

Use information from the pid file (including its last modification time) to guess the status of the corresponding process, return the status (true means that the process seems to be running); in list context, also return an informative message and an LSB compatible exit code; supported options:

• freshness — maximum age allowed for an active pid file
• timeout — check multiple times until success or timeout

pf_quit(PATH[, OPTIONS])

Tell the process corresponding to the pid file to quit (setting its action to "quit"), wait a bit to check that it indeed stopped and kill it using No::Worries::Proc's proc_terminate() if everything else fails; supported options:

• callback — code that will be called with information to report
• linger — maximum time to wait after having told the process to quit (default: 5)
• kill — kill specification to use when killing the process

🦋 SEE ALSO 🦋

Go peek at <http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html>, plus No::Worries and No::Worries::Proc. These are the friends in the group chat. 🫶

👑 AUTHOR 👑

Lionel Cons <http://cern.ch/lionel.cons>

Copyright (C) CERN 2012-2019

That's the whole page, bestie! Source/version: perl v5.32.1; date: 2021-10-18; footer label: No::Wor...PidFile(3). Bye! 💖🦋✨