1No::Worries::PidFile(3)User Contributed Perl DocumentatioNno::Worries::PidFile(3)
2
3
4
6 No::Worries::PidFile - pid file handling without worries
7
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
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
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
137 <http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html>,
138 No::Worries, No::Worries::Proc.
139
141 Lionel Cons <http://cern.ch/lionel.cons>
142
143 Copyright (C) CERN 2012-2019
144
145
146
147perl v5.36.0 2022-07-22 No::Worries::PidFile(3)