No::Worries::PidFile(3pm)

1No::Worries::PidFile(3)User Contributed Perl DocumentatioNno::Worries::PidFile(3)
2
3
4

NAME

6       No::Worries::PidFile - pid file handling without worries
7

SYNOPSIS

9         use No::Worries::PidFile qw(*);
10
11         # idiomatic daemon code
12         pf_set($pidfile);
13         while (1) {
14             ...
15             $action = pf_check($pidfile);
16             last if $action eq "quit";
17             pf_touch($pidfile);
18             ...
19         }
20         pf_unset($pidfile);
21
22         # idiomatic daemon code with sleeping
23         pf_set($pidfile);
24         while (1) {
25             ...
26             pf_sleep($pidfile, time => 5) or last;
27             ...
28         }
29         pf_unset($pidfile);
30
31         # here is how to handle a --status option
32         if ($Option{status}) {
33             ($status, $message, $code) = pf_status($pidfile, freshness => 10);
34             printf("myprog %s\n", $message);
35             exit($code);
36         }
37
38         # here is how to handle a --quit option
39         if ($Option{quit}) {
40             pf_quit($pidfile,
41                 linger   => 10,
42                 callback => sub { printf("myprog %s\n", $_[0]) },
43             );
44         }
45

DESCRIPTION

47       This module eases pid file handling by providing high level functions
48       to set, check, touch and unset pid files. All the functions die() on
49       error.
50
51       The pid file usually contains the process id on a single line, followed
52       by a newline. However, it can also be followed by an optional action,
53       also followed by a newline. This allows some kind of inter-process
54       communication: a process using pf_quit() will append the "quit" action
55       to the pid file and the owning process will detect this via pf_check().
56
57       All the functions properly handle concurrency. For instance, when two
58       processes start at the exact same time and call pf_set(), only one will
59       succeed and the other one will get an error.
60
61       Since an existing pid file will make pf_set() fail, it is very
62       important to remove the pid file in all situations, including errors.
63       The recommended way to do so is to use an END block:
64
65         # we need to know about transient processes
66         use No::Worries::Proc qw();
67         # we need to record what needs to be cleaned up
68         our(%NeedsCleanup);
69         # we set the pid file here and remember to clean it up
70         pf_set($pidfile);
71         $NeedsCleanup{pidfile} = 1;
72         # ... anything can happen here ...
73         # cleanup code in an END block
74         END {
75             # transient processes do not need cleanup
76             return if $No::Worries::Proc::Transient;
77             # cleanup the pid file if needed
78             pf_unset($pidfile) if $NeedsCleanup{pidfile};
79         }
80

FUNCTIONS

82       This module provides the following functions (none of them being
83       exported by default):
84
85       pf_set(PATH[, OPTIONS])
86           set the pid file by writing the given pid at the given path;
87           supported options:
88
89           •   "pid": the pid to use (default: $$)
90
91       pf_check(PATH[, OPTIONS])
92           check the pid file and make sure the given pid is present, also
93           return the action in the pid file or the empty string; supported
94           options:
95
96           •   "pid": the pid to use (default: $$)
97
98       pf_unset(PATH)
99           unset the pid file by removing the given path
100
101       pf_touch(PATH)
102           touch the pid file (i.e. update the file modification time) to show
103           that the owning process is alive
104
105       pf_sleep(PATH[, OPTIONS])
106           check and touch the pid file and eventually sleep for the givent
107           amount of time, returning true if the program should continue or
108           false if it has been told to stop via pf_quit(); supported options:
109
110           •   "time": the time to sleep (default: 1, can be fractional)
111
112       pf_status(PATH[, OPTIONS])
113           use information from the pid file (including its last modification
114           time) to guess the status of the corresponding process, return the
115           status (true means that the process seems to be running); in list
116           context, also return an informative message and an LSB compatible
117           exit code; supported options:
118
119           •   "freshness": maximum age allowed for an active pid file
120
121           •   "timeout": check multiple times until success or timeout
122
123       pf_quit(PATH[, OPTIONS])
124           tell the process corresponding to the pid file to quit (setting its
125           action to "quit"), wait a bit to check that it indeed stopped and
126           kill it using No::Worries::Proc's proc_terminate() if everything
127           else fails; supported options:
128
129           •   "callback": code that will be called with information to report
130
131           •   "linger": maximum time to wait after having told the process to
132               quit (default: 5)
133
134           •   "kill": kill specification to use when killing the process
135

AUTHOR

141       Lionel Cons <http://cern.ch/lionel.cons>
142
143       Copyright (C) CERN 2012-2019
144
145
146
147perl v5.34.0                      2021-10-18           No::Worries::PidFile(3)

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

SEE ALSO

AUTHOR