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
 144                 receive_signal `{
 145                 SignalHandler last_handler;
 146                 if (signal < 32 && signal >=0) {
 147                         struct sigaction act;
 148                         sigemptyset(&act.sa_mask);
 149                         act.sa_flags = 0;
 150                         act.sa_handler = receiver;
 151
 152                         sigaction(signal, &act, NULL);
 153
 154                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 155                         if (last_handler != NULL)
 156                                 SignalHandler_decr_ref(last_handler);
 157
 158                         nit_signals_list[signal].handler = self;
 159                         SignalHandler_incr_ref(self);
 160
 161                         nit_signals_list[signal].safely = safely;
 162                         nit_SignalHandler_receive_signal = SignalHandler_receive_signal;
 163                 }
 164         `}
 165
 166         # Set to ignore the signal
 167         fun ignore_signal(signal: Int) `{
 168                 SignalHandler last_handler;
 169                 if (signal < 32 && signal >=0) {
 170                         struct sigaction act;
 171                         sigemptyset(&act.sa_mask);
 172                         act.sa_flags = 0;
 173                         act.sa_handler = SIG_IGN;
 174                         sigaction(signal, &act, NULL);
 175
 176                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 177                         if (last_handler != NULL)
 178                                 SignalHandler_decr_ref(last_handler);
 179                 }
 180         `}
 181
 182         # Set default action for the signal
 183         fun default_signal(signal: Int) `{
 184                 SignalHandler last_handler;
 185                 if (signal < 32 && signal >=0) {
 186                         struct sigaction act;
 187                         sigemptyset(&act.sa_mask);
 188                         act.sa_flags = 0;
 189                         act.sa_handler = SIG_DFL;
 190                         sigaction(signal, &act, NULL);
 191
 192                         last_handler = (SignalHandler)nit_signals_list[signal].handler;
 193                         if (last_handler != NULL)
 194                                 SignalHandler_decr_ref(last_handler);
 195                 }
 196         `}
 197 end
 198
 199 redef interface Object
 200
 201         # Check signals for safe operation
 202         # will callback receiver of raised signals
 203         # can callback any instance of SignalHandler, not just this one
 204         protected fun check_signals: Bool is extern import SignalHandler.receive_signal `{
 205                 int sig;
 206                 int raised_something = 0;
 207
 208                 for (sig = 0; sig < 32; sig ++)
 209                         if (nit_signals_list[sig].raised) {
 210                                 nit_signals_list[sig].raised = 0;
 211                                 raised_something = 1;
 212                                 SignalHandler handler = (SignalHandler)nit_signals_list[sig].handler;
 213                                 SignalHandler_receive_signal(handler, sig);
 214                         }
 215
 216                 return raised_something;
 217         `}
 218
 219         # Set alarm signal
 220         # can callback any instance of SignalHandler, not just this one
 221         protected fun set_alarm(sec: Int) `{ alarm(sec); `}
 222 end
 223
 224 redef class Process
 225         # Send a signal to the process
 226         fun signal(signal: Int) do native_kill(id, signal)
 227
 228         # Send the kill signal to the process
 229         fun kill do signal(sigkill)
 230
 231         # Native implementation of `signal`
 232         private fun native_kill(pid, signal: Int) `{ kill(pid, signal); `}
 233 end
 234
 235 # Hang up detected on controlling terminal or death of controlling process
 236 fun sighup: Int do return 1
 237
 238 # Issued if the user sends an interrupt signal
 239 fun sigint: Int do return 2
 240
 241 # Issued if the user sends a quit signal
 242 fun sigquit: Int do return 3
 243
 244 # Issued if the user attempts to execute an illegal, malformed, unknown, or privileged instruction
 245 fun sigill: Int do return 4
 246
 247 # Issued when an exception occurs: a condition that a debugger has requested to be informed of
 248 fun sigtrap: Int do return 5
 249
 250 # This signal is sent to a process to tell it to abort, i. e. to terminate
 251 fun sigabrt: Int do return 6
 252
 253 # This signal is sent to a process when it causes a bus error
 254 fun sigbus: Int do return 7
 255
 256 # Issued if an illegal mathematical operation is attempted
 257 fun sigfpe: Int do return 8
 258
 259 # If a process gets this signal it must quit immediately and will not perform any clean-up operations
 260 fun sigkill: Int do return 9
 261
 262 # Sent to a process to indicate user-defined conditions
 263 fun sigusr1: Int do return 10
 264
 265 # Sent to a process when it makes an invalid virtual memory reference, or segmentation fault
 266 fun sigsegv: Int do return 11
 267
 268 # Sent to a process to indicate user-defined conditions
 269 fun sigusr2: Int do return 12
 270
 271 # Sent to a process when it attempts to write to a pipe without a process connected to the other end
 272 fun sigpipe: Int do return 13
 273
 274 # Alarm Clock signal
 275 fun sigalarm: Int do return 14
 276
 277 # Software termination signal
 278 fun sigterm: Int do return 15
 279
 280 # Sent to a process when a child process terminates or is interrupted
 281 fun sigchild: Int do return 17
 282
 283 # Tell the operating system to continue (restart) a process previously paused by the SIGSTOP or SIGTSTP signal
 284 fun sigcont: Int do return 18
 285
 286 # Tell the operating system to stop a process
 287 fun sigstop: Int do return 19
 288
 289 # Sent to a process by its terminal to request it to stop temporarily
 290 fun sigtstp: Int do return 20
 291
 292 # Sent to a process when a socket has urgent or out-of-band data available to read
 293 fun sigurg: Int do return 23
 294
 295 # Sent to a process when it has used the CPU for a duration that exceeds a user-settable value
 296 fun sigxcpu: Int do return 24
 297
 298 # Sent to a process when it grows a file larger than the maximum allowed size
 299 fun sigxfsz: Int do return 25
 300
 301 # Virtual timer expired
 302 fun sigvtalrm: Int do return 26
 303
 304 # Profiling timer expired
 305 fun sigprof: Int do return 27
 306
 307 # Sent to a process when its controlling terminal changes its window size
 308 fun sigwinch: Int do return 28
 309
 310 # Sent to a process when the system experiences a power failure
 311 fun sigpwr: Int do return 30
 312
 313 # Sent to a process when it passes a bad argument to a system call
 314 fun sigsys: Int do return 31