lib/signals.nit

   1 # This file is part of NIT (http://www.nitlanguage.org).
   2 #
   3 # Copyright 2011 Alexis Laferrière <alexis.laf@xymus.net>
   4 #
   5 # Licensed under the Apache License, Version 2.0 (the "License");
   6 # you may not use this file except in compliance with the License.
   7 # You may obtain a copy of the License at
   8 #
   9 #     http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 # Unless required by applicable law or agreed to in writing, software
  12 # distributed under the License is distributed on an "AS IS" BASIS,
  13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17 # Module to manage standard C signals
  18 #
  19 # Common usage imply 5 steps:
  20 #
  21 # 1. Implement the `SignalHandler` interface
  22 # 2. `redef receive_signal_unsafe` to handle `sigsegv`
  23 # 3. `redef receive_signal` to handle other signals safely
  24 # 4, Notify what signals to handle with `handle_signal`
  25 # 5. If using the safe handler method, routinely call `check_signals`
  26 #
  27 # Usage example:
  28 #
  29 # ~~~~
  30 # class MyReceiver
  31 #       super SignalHandler
  32 #
  33 #       redef fun receive_signal(signal)
  34 #       do
  35 #               print "received safely {signal}"
  36 #               if signal == sigalarm then print "Alarm!"
  37 #       end
  38 #       redef fun receive_signal_unsafe( signal ) do print "received unsafely {signal}"
  39 # end
  40 #
  41 # var r = new MyReceiver
  42 #
  43 # # Handle `sigsegv` signal unsafely (the only way for this one)
  44 # r.handle_signal(sigsegv, false)
  45 #
  46 # # Handle `sigint` and `sigalarm` safely
  47 # r.handle_signal(sigint, true)
  48 # r.handle_signal(sigalarm, true)
  49 #
  50 # # Ask system to receive a `sigalarm` signal in 1 second
  51 # set_alarm(1)
  52 #
  53 # loop
  54 #       # Check signals and callback `receive_signal`
  55 #       var hit = check_signals
  56 #
  57 #       if hit then break
  58 # end
  59 # ~~~~
  60 module signals
  61
  62 `{
  63         #undef _POSIX_SOURCE
  64         #define _POSIX_SOURCE 1
  65         #include <signal.h>
  66         #include <stdio.h>
  67
  68         /*
  69         */
  70         void (*nit_SignalHandler_receive_signal)(void* self, long signal);
  71
  72         /*
  73                 Structure to manage each possible signals
  74                 are used in an array of 32 maximum signals.
  75                 This array is global to the software.
  76         */
  77         struct nit_signals_ent {
  78                 char raised; /* !=0 if has been raised */
  79                 void* handler; /* instance to receive call */
  80                 char safely; /* if !=0 then manage signal safely, otherwise react when raised */
  81         } nit_signals_list[32] = {0x0};
  82
  83         /* Receiver to all signals
  84                 If unsafe, it calls directly the Nit receiver,
  85                 otherwise it marks the signal as raised and returns.
  86         */
  87         void receiver(int sig)
  88         {
  89                 if (sig < 32 && sig >=0)
  90                 {
  91                         if (nit_signals_list[sig].safely) {
  92                                 nit_signals_list[sig].raised += 1;
  93                         } else {
  94                                 nit_SignalHandler_receive_signal(nit_signals_list[sig].handler, sig);
  95                         }
  96                 }
  97         }
  98 `}
  99
 100 # Receives the callback from system when a given signal arise
 101 interface SignalHandler
 102         # Invoked after a call to `check_signals` if a signal has been raised
 103         # (should be redefed by subclasses)
 104         #
 105         # Should be used by most signals except `sigkill` and `sigstop` since they
 106         # cannot be caught, blocked or ignored.
 107         #
 108         #     class MyReceiver
 109         #         super SignalHandler
 110         #
 111         #         redef fun receive_signal(signal) do print "received safely {signal}"
 112         #     end
 113         #
 114         #     var r = new MyReceiver
 115         #     r.handle_signal(sigint, true) # will call back when "check_signals" is called
 116         #     # ...
 117         #     check_signals # if a signal was received, it will invoke `r.receive_signal`
 118         fun receive_signal(signal: Int) do end
 119
 120         # Called immediatly on receiving an unsafe signal (should be redefed by subclasses)
 121         #
 122         # Should be used for `sigkill` and `sigstop` since they cannot be caught,
 123         # blocked or ignored.
 124         #
 125         # You should consider this methods as being fragile. It should be implemented in C
 126         # and you should not do too much callbacks to Nit.
 127         #
 128         #     class MyReceiver
 129         #         super SignalHandler
 130         #
 131         #         redef fun receive_signal_unsafe(signal) do print "received unsafely {signal}"
 132         #     end
 133         #
 134         #     var r = new MyReceiver
 135         #     r.handle_signal(sigsegv, false) # `r.receive_signal_unsafe` will be invoked on sigsegv
 136         fun receive_signal_unsafe(signal: Int) do end
 137
 138         # Set the receiver as the handler of the signal
 139         #
 140         # If `safely`, receiver will be called when `check_signals` in invoked
 141         # otherwise the receiver is invoked when the signal is raised, it may
 142         # crash the Nit system but is unavoidable for unstoppable signals.
 143         fun handle_signal(signal: Int, safely: Bool) import receive_signal `{
 144                 SignalHandler last_handler;
 145                 if (signal < 32 && signal >=0) {
 146                         struct sigaction act;
 147                         sigemptyset(&act.sa_mask);
 148                         act.sa_flags = 0;
 149                         act.sa_handler = receiver;
 150
 151                         sigaction(signal, &act, NULL);
 152
 153                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 154                         if (last_handler != NULL)
 155                                 SignalHandler_decr_ref(last_handler);
 156
 157                         nit_signals_list[signal].handler = self;
 158                         SignalHandler_incr_ref(self);
 159
 160                         nit_signals_list[signal].safely = safely;
 161                         nit_SignalHandler_receive_signal = SignalHandler_receive_signal;
 162                 }
 163         `}
 164
 165         # Set to ignore the signal
 166         fun ignore_signal(signal: Int) `{
 167                 SignalHandler last_handler;
 168                 if (signal < 32 && signal >=0) {
 169                         struct sigaction act;
 170                         sigemptyset(&act.sa_mask);
 171                         act.sa_flags = 0;
 172                         act.sa_handler = SIG_IGN;
 173                         sigaction(signal, &act, NULL);
 174
 175                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 176                         if (last_handler != NULL)
 177                                 SignalHandler_decr_ref(last_handler);
 178                 }
 179         `}
 180
 181         # Set default action for the signal
 182         fun default_signal(signal: Int) `{
 183                 SignalHandler last_handler;
 184                 if (signal < 32 && signal >=0) {
 185                         struct sigaction act;
 186                         sigemptyset(&act.sa_mask);
 187                         act.sa_flags = 0;
 188                         act.sa_handler = SIG_DFL;
 189                         sigaction(signal, &act, NULL);
 190
 191                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 192                         if (last_handler != NULL)
 193                                 SignalHandler_decr_ref(last_handler);
 194                 }
 195         `}
 196 end
 197
 198 redef interface Object
 199
 200         # Check signals for safe operation
 201         # will callback receiver of raised signals
 202         # can callback any instance of SignalHandler, not just this one
 203         protected fun check_signals: Bool is extern import SignalHandler.receive_signal `{
 204                 int sig;
 205                 int raised_something = 0;
 206
 207                 for (sig = 0; sig < 32; sig ++)
 208                         if (nit_signals_list[sig].raised) {
 209                                 nit_signals_list[sig].raised = 0;
 210                                 raised_something = 1;
 211                                 SignalHandler handler = (SignalHandler)nit_signals_list[sig].handler;
 212                                 SignalHandler_receive_signal(handler, sig);
 213                         }
 214
 215                 return raised_something;
 216         `}
 217
 218         # Set alarm signal
 219         # can callback any instance of SignalHandler, not just this one
 220         protected fun set_alarm(sec: Int) `{ alarm(sec); `}
 221 end
 222
 223 redef class Process
 224         # Send a signal to the process
 225         fun signal(signal: Int) do native_kill(id, signal)
 226
 227         # Send the kill signal to the process
 228         fun kill do signal(sigkill)
 229
 230         # Native implementation of `signal`
 231         private fun native_kill(pid, signal: Int) `{ kill(pid, signal); `}
 232 end
 233
 234 # Hang up detected on controlling terminal or death of controlling process
 235 fun sighup: Int do return 1
 236
 237 # Issued if the user sends an interrupt signal
 238 fun sigint: Int do return 2
 239
 240 # Issued if the user sends a quit signal
 241 fun sigquit: Int do return 3
 242
 243 # Issued if the user attempts to execute an illegal, malformed, unknown, or privileged instruction
 244 fun sigill: Int do return 4
 245
 246 # Issued when an exception occurs: a condition that a debugger has requested to be informed of
 247 fun sigtrap: Int do return 5
 248
 249 # This signal is sent to a process to tell it to abort, i. e. to terminate
 250 fun sigabrt: Int do return 6
 251
 252 # This signal is sent to a process when it causes a bus error
 253 fun sigbus: Int do return 7
 254
 255 # Issued if an illegal mathematical operation is attempted
 256 fun sigfpe: Int do return 8
 257
 258 # If a process gets this signal it must quit immediately and will not perform any clean-up operations
 259 fun sigkill: Int do return 9
 260
 261 # Sent to a process to indicate user-defined conditions
 262 fun sigusr1: Int do return 10
 263
 264 # Sent to a process when it makes an invalid virtual memory reference, or segmentation fault
 265 fun sigsegv: Int do return 11
 266
 267 # Sent to a process to indicate user-defined conditions
 268 fun sigusr2: Int do return 12
 269
 270 # Sent to a process when it attempts to write to a pipe without a process connected to the other end
 271 fun sigpipe: Int do return 13
 272
 273 # Alarm Clock signal
 274 fun sigalarm: Int do return 14
 275
 276 # Software termination signal
 277 fun sigterm: Int do return 15
 278
 279 # Sent to a process when a child process terminates or is interrupted
 280 fun sigchild: Int do return 17
 281
 282 # Tell the operating system to continue (restart) a process previously paused by the SIGSTOP or SIGTSTP signal
 283 fun sigcont: Int do return 18
 284
 285 # Tell the operating system to stop a process
 286 fun sigstop: Int do return 19
 287
 288 # Sent to a process by its terminal to request it to stop temporarily
 289 fun sigtstp: Int do return 20
 290
 291 # Sent to a process when a socket has urgent or out-of-band data available to read
 292 fun sigurg: Int do return 23
 293
 294 # Sent to a process when it has used the CPU for a duration that exceeds a user-settable value
 295 fun sigxcpu: Int do return 24
 296
 297 # Sent to a process when it grows a file larger than the maximum allowed size
 298 fun sigxfsz: Int do return 25
 299
 300 # Virtual timer expired
 301 fun sigvtalrm: Int do return 26
 302
 303 # Profiling timer expired
 304 fun sigprof: Int do return 27
 305
 306 # Sent to a process when its controlling terminal changes its window size
 307 fun sigwinch: Int do return 28
 308
 309 # Sent to a process when the system experiences a power failure
 310 fun sigpwr: Int do return 30
 311
 312 # Sent to a process when it passes a bad argument to a system call
 313 fun sigsys: Int do return 31