The previous attempt at using a pipe to guarantee astcanary shutdown did not work.
[asterisk/asterisk.git] / utils / astcanary.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2007, Digium, Inc.
5  *
6  * Tilghman Lesher <tlesher AT digium DOT com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #include <sys/types.h>
20 #include <sys/stat.h>
21 #include <sys/time.h>
22 #include <sys/resource.h>
23 #include <utime.h>
24 #include <fcntl.h>
25 #include <unistd.h>
26 #include <stdlib.h>
27 #include <string.h>
28
29 /*!\brief
30  * At one time, canaries were carried along with coal miners down
31  * into a mine.  Their purpose was to alert the miners when they
32  * had drilled into a pocket of methane gas or another noxious
33  * substance.  The canary, being the most sensitive animal, would
34  * immediately fall over.  Seeing this, the miners could take
35  * action to escape the mine, seeing an imminent danger.
36  *
37  * This process serves a similar purpose, though with the realtime
38  * priority being the reason.  When a thread starts running away
39  * with the processor, it is typically difficult to tell what
40  * thread caused the problem, as the machine acts as if it is
41  * locked up (in fact, what has happened is that Asterisk runs at
42  * a higher priority than even the login shell, so the runaway
43  * thread hogs all available CPU time.
44  *
45  * If that happens, this canary process will cease to get any
46  * process time, which we can monitor with a realtime thread in
47  * Asterisk.  Should that happen, that monitoring thread may take
48  * immediate action to slow down Asterisk to regular priority,
49  * thus allowing an administrator to login to the system and
50  * restart Asterisk or perhaps take another course of action
51  * (such as retrieving a backtrace to let the developers know
52  * what precisely went wrong).
53  *
54  * Note that according to POSIX.1, all threads inside a single
55  * process must share the same priority, so when the monitoring
56  * thread deprioritizes itself, it deprioritizes all threads at
57  * the same time.  This is also why this canary must exist as a
58  * completely separate process and not simply as a thread within
59  * Asterisk itself.
60  *
61  * Quote:
62  * "The nice value set with setpriority() shall be applied to the
63  * process. If the process is multi-threaded, the nice value shall
64  * affect all system scope threads in the process."
65  *
66  * Source:
67  * http://www.opengroup.org/onlinepubs/000095399/functions/setpriority.html
68  *
69  * In answer to the question, what aren't system scope threads, the
70  * answer is, in Asterisk, nothing.  Process scope threads are the
71  * alternative, but they aren't supported in Linux.
72  */
73
74 static const char explanation[] =
75 "This file is created when Asterisk is run with a realtime priority (-p).  It\n"
76 "must continue to exist, and the astcanary process must be allowed to continue\n"
77 "running, or else the Asterisk process will, within a short period of time,\n"
78 "slow itself down to regular priority.\n\n"
79 "The technical explanation for this file is to provide an assurance to Asterisk\n"
80 "that there are no threads that have gone into runaway mode, thus hogging the\n"
81 "CPU, and making the Asterisk machine seem to be unresponsive.  When that\n"
82 "happens, the astcanary process will be unable to update the timestamp on this\n"
83 "file, and Asterisk will notice within 120 seconds and react.  Slowing the\n"
84 "Asterisk process down to regular priority will permit an administrator to\n"
85 "intervene, thus avoiding a need to reboot the entire machine.\n";
86
87 int main(int argc, char *argv[])
88 {
89         int fd;
90         pid_t parent;
91
92         if (argc < 3) {
93                 fprintf(stderr, "Usage: %s <monitor-filename> <ppid>\n", argv[0]);
94                 exit(1);
95         }
96
97         /* Run at normal priority */
98         setpriority(PRIO_PROCESS, 0, 0);
99
100         /*!\note
101          * See http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap03.html#tag_03_265
102          * for a justification of this approach.  The PPID after the creator dies in Linux and
103          * most other Unix-like systems will be 1, but this is not strictly the case.  The POSIX
104          * specification allows it to be an implementation-defined system process.  However, it
105          * most certainly will not be the original parent PID, which makes the following code
106          * POSIX-compliant.
107          */
108         for (parent = atoi(argv[2]); parent == getppid() ;) {
109                 /* Update the modification times (checked from Asterisk) */
110                 if (utime(argv[1], NULL)) {
111                         /* Recreate the file if it doesn't exist */
112                         if ((fd = open(argv[1], O_RDWR | O_TRUNC | O_CREAT, 0777)) > -1) {
113                                 if (write(fd, explanation, strlen(explanation)) < 0) {
114                                         exit(1);
115                                 }
116                                 close(fd);
117                         } else {
118                                 exit(1);
119                         }
120                         continue;
121                 }
122
123                 /* Run occasionally */
124                 sleep(5);
125         }
126
127         /* Exit when the parent dies */
128         return 0;
129 }
130