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 # ANSI C signal handling
  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         #include <unistd.h>
  68
  69         /*
  70         */
  71         void (*nit_SignalHandler_receive_signal)(void* self, long signal);
  72
  73         /*
  74                 Structure to manage each possible signals
  75                 are used in an array of 32 maximum signals.
  76                 This array is global to the software.
  77         */
  78         struct nit_signals_ent {
  79                 char raised; /* !=0 if has been raised */
  80                 void* handler; /* instance to receive call */
  81                 char safely; /* if !=0 then manage signal safely, otherwise react when raised */
  82         } nit_signals_list[32] = {{0}};
  83
  84         /* Receiver to all signals
  85                 If unsafe, it calls directly the Nit receiver,
  86                 otherwise it marks the signal as raised and returns.
  87         */
  88         void receiver(int sig)
  89         {
  90                 if (sig < 32 && sig >=0)
  91                 {
  92                         if (nit_signals_list[sig].safely) {
  93                                 nit_signals_list[sig].raised += 1;
  94                         } else {
  95                                 nit_SignalHandler_receive_signal(nit_signals_list[sig].handler, sig);
  96                         }
  97                 }
  98         }
  99 `}
 100
 101 # Receives the callback from system when a given signal arise
 102 interface SignalHandler
 103         # Invoked after a call to `check_signals` if a signal has been raised
 104         # (should be redefed by subclasses)
 105         #
 106         # Should be used by most signals except `sigkill` and `sigstop` since they
 107         # cannot be caught, blocked or ignored.
 108         #
 109         #     class MyReceiver
 110         #         super SignalHandler
 111         #
 112         #         redef fun receive_signal(signal) do print "received safely {signal}"
 113         #     end
 114         #
 115         #     var r = new MyReceiver
 116         #     r.handle_signal(sigint, true) # will call back when "check_signals" is called
 117         #     # ...
 118         #     check_signals # if a signal was received, it will invoke `r.receive_signal`
 119         fun receive_signal(signal: Int) do end
 120
 121         # Called immediatly on receiving an unsafe signal (should be redefed by subclasses)
 122         #
 123         # Should be used for `sigkill` and `sigstop` since they cannot be caught,
 124         # blocked or ignored.
 125         #
 126         # You should consider this methods as being fragile. It should be implemented in C
 127         # and you should not do too much callbacks to Nit.
 128         #
 129         #     class MyReceiver
 130         #         super SignalHandler
 131         #
 132         #         redef fun receive_signal_unsafe(signal) do print "received unsafely {signal}"
 133         #     end
 134         #
 135         #     var r = new MyReceiver
 136         #     r.handle_signal(sigsegv, false) # `r.receive_signal_unsafe` will be invoked on sigsegv
 137         fun receive_signal_unsafe(signal: Int) do end
 138
 139         # Set the receiver as the handler of the signal
 140         #
 141         # If `safely`, receiver will be called when `check_signals` in invoked
 142         # otherwise the receiver is invoked when the signal is raised, it may
 143         # crash the Nit system but is unavoidable for unstoppable signals.
 144         fun handle_signal(signal: Int, safely: Bool) import receive_signal `{
 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                 #ifdef SignalHandler_decr_ref
 154                         SignalHandler last_handler = (SignalHandler)nit_signals_list[signal].handler;
 155                         if (last_handler != NULL)
 156                                 SignalHandler_decr_ref(last_handler);
 157                 #endif
 158
 159                         nit_signals_list[signal].handler = self;
 160
 161                 #ifdef SignalHandler_incr_ref
 162                         SignalHandler_incr_ref(self);
 163                 #endif
 164
 165                         nit_signals_list[signal].safely = safely;
 166
 167                         nit_SignalHandler_receive_signal = SignalHandler_receive_signal;
 168                 }
 169         `}
 170
 171         # Set to ignore the signal
 172         fun ignore_signal(signal: Int) `{
 173                 if (signal < 32 && signal >=0) {
 174                         struct sigaction act;
 175                         sigemptyset(&act.sa_mask);
 176                         act.sa_flags = 0;
 177                         act.sa_handler = SIG_IGN;
 178                         sigaction(signal, &act, NULL);
 179
 180                 #ifdef SignalHandler_decr_ref
 181                         SignalHandler last_handler = (SignalHandler)nit_signals_list[signal].handler;
 182                         if (last_handler != NULL)
 183                                 SignalHandler_decr_ref(last_handler);
 184                 #endif
 185                 }
 186         `}
 187
 188         # Set default action for the signal
 189         fun default_signal(signal: Int) `{
 190                 if (signal < 32 && signal >=0) {
 191                         struct sigaction act;
 192                         sigemptyset(&act.sa_mask);
 193                         act.sa_flags = 0;
 194                         act.sa_handler = SIG_DFL;
 195                         sigaction(signal, &act, NULL);
 196
 197                 #ifdef SignalHandler_decr_ref
 198                         SignalHandler last_handler = (SignalHandler)nit_signals_list[signal].handler;
 199                         if (last_handler != NULL)
 200                                 SignalHandler_decr_ref(last_handler);
 201                 #endif
 202                 }
 203         `}
 204 end
 205
 206 # Check signals for safe operation
 207 # will callback receiver of raised signals
 208 # can callback any instance of SignalHandler, not just this one
 209 fun check_signals: Bool is extern import SignalHandler.receive_signal `{
 210         int sig;
 211         int raised_something = 0;
 212
 213         for (sig = 0; sig < 32; sig ++)
 214                 if (nit_signals_list[sig].raised) {
 215                         nit_signals_list[sig].raised = 0;
 216                         raised_something = 1;
 217                         SignalHandler handler = (SignalHandler)nit_signals_list[sig].handler;
 218                         SignalHandler_receive_signal(handler, sig);
 219                 }
 220
 221         return raised_something;
 222 `}
 223
 224 # Set alarm signal
 225 # can callback any instance of SignalHandler, not just this one
 226 fun set_alarm(sec: Int) `{ alarm(sec); `}
 227
 228 redef class Process
 229         # Send a signal to the process
 230         fun signal(signal: Int) do native_kill(id, signal)
 231
 232         # Send the kill signal to the process
 233         fun kill do signal(sigkill)
 234
 235         # Native implementation of `signal`
 236         private fun native_kill(pid, signal: Int) `{ kill(pid, signal); `}
 237 end
 238
 239 # Hang up detected on controlling terminal or death of controlling process
 240 fun sighup: Int do return 1
 241
 242 # Issued if the user sends an interrupt signal
 243 fun sigint: Int do return 2
 244
 245 # Issued if the user sends a quit signal
 246 fun sigquit: Int do return 3
 247
 248 # Issued if the user attempts to execute an illegal, malformed, unknown, or privileged instruction
 249 fun sigill: Int do return 4
 250
 251 # Issued when an exception occurs: a condition that a debugger has requested to be informed of
 252 fun sigtrap: Int do return 5
 253
 254 # This signal is sent to a process to tell it to abort, i. e. to terminate
 255 fun sigabrt: Int do return 6
 256
 257 # This signal is sent to a process when it causes a bus error
 258 fun sigbus: Int do return 7
 259
 260 # Issued if an illegal mathematical operation is attempted
 261 fun sigfpe: Int do return 8
 262
 263 # If a process gets this signal it must quit immediately and will not perform any clean-up operations
 264 fun sigkill: Int do return 9
 265
 266 # Sent to a process to indicate user-defined conditions
 267 fun sigusr1: Int do return 10
 268
 269 # Sent to a process when it makes an invalid virtual memory reference, or segmentation fault
 270 fun sigsegv: Int do return 11
 271
 272 # Sent to a process to indicate user-defined conditions
 273 fun sigusr2: Int do return 12
 274
 275 # Sent to a process when it attempts to write to a pipe without a process connected to the other end
 276 fun sigpipe: Int do return 13
 277
 278 # Alarm Clock signal
 279 fun sigalarm: Int do return 14
 280
 281 # Software termination signal
 282 fun sigterm: Int do return 15
 283
 284 # Sent to a process when a child process terminates or is interrupted
 285 fun sigchild: Int do return 17
 286
 287 # Tell the operating system to continue (restart) a process previously paused by the SIGSTOP or SIGTSTP signal
 288 fun sigcont: Int do return 18
 289
 290 # Tell the operating system to stop a process
 291 fun sigstop: Int do return 19
 292
 293 # Sent to a process by its terminal to request it to stop temporarily
 294 fun sigtstp: Int do return 20
 295
 296 # Sent to a process when a socket has urgent or out-of-band data available to read
 297 fun sigurg: Int do return 23
 298
 299 # Sent to a process when it has used the CPU for a duration that exceeds a user-settable value
 300 fun sigxcpu: Int do return 24
 301
 302 # Sent to a process when it grows a file larger than the maximum allowed size
 303 fun sigxfsz: Int do return 25
 304
 305 # Virtual timer expired
 306 fun sigvtalrm: Int do return 26
 307
 308 # Profiling timer expired
 309 fun sigprof: Int do return 27
 310
 311 # Sent to a process when its controlling terminal changes its window size
 312 fun sigwinch: Int do return 28
 313
 314 # Sent to a process when the system experiences a power failure
 315 fun sigpwr: Int do return 30
 316
 317 # Sent to a process when it passes a bad argument to a system call
 318 fun sigsys: Int do return 31