doc/guide/src/MLtonSignal.adoc

   1 MLtonSignal
   2 ===========
   3
   4 [source,sml]
   5 ----
   6 signature MLTON_SIGNAL =
   7    sig
   8       type t = Posix.Signal.signal
   9       type signal = t
  10
  11       structure Handler:
  12          sig
  13             type t
  14
  15             val default: t
  16             val handler: (Thread.Runnable.t -> Thread.Runnable.t) -> t
  17             val ignore: t
  18             val isDefault: t -> bool
  19             val isIgnore: t -> bool
  20             val simple: (unit -> unit) -> t
  21          end
  22
  23       structure Mask:
  24          sig
  25             type t
  26
  27             val all: t
  28             val allBut: signal list -> t
  29             val block: t -> unit
  30             val getBlocked: unit -> t
  31             val isMember: t * signal -> bool
  32             val none: t
  33             val setBlocked: t -> unit
  34             val some: signal list -> t
  35             val unblock: t -> unit
  36          end
  37
  38       val getHandler: t -> Handler.t
  39       val handled: unit -> Mask.t
  40       val prof: t
  41       val restart: bool ref
  42       val setHandler: t * Handler.t -> unit
  43       val suspend: Mask.t -> unit
  44       val vtalrm: t
  45    end
  46 ----
  47
  48 Signals handlers are functions from (runnable) threads to (runnable)
  49 threads.  When a signal arrives, the corresponding signal handler is
  50 invoked, its argument being the thread that was interrupted by the
  51 signal.  The signal handler runs asynchronously, in its own thread.
  52 The signal handler returns the thread that it would like to resume
  53 execution (this is often the thread that it was passed).  It is an
  54 error for a signal handler to raise an exception that is not handled
  55 within the signal handler itself.
  56
  57 A signal handler is never invoked while the running thread is in a
  58 critical section (see <:MLtonThread:>).  Invoking a signal handler
  59 implicitly enters a critical section and the normal return of a signal
  60 handler implicitly exits the critical section; hence, a signal handler
  61 is never interrupted by another signal handler.
  62
  63 * `type t`
  64 +
  65 the type of signals.
  66
  67 * `type Handler.t`
  68 +
  69 the type of signal handlers.
  70
  71 * `Handler.default`
  72 +
  73 handles the signal with the default action.
  74
  75 * `Handler.handler f`
  76 +
  77 returns a handler `h` such that when a signal `s` is handled by `h`,
  78 `f` will be passed the thread that was interrupted by `s` and should
  79 return the thread that will resume execution.
  80
  81 * `Handler.ignore`
  82 +
  83 is a handler that will ignore the signal.
  84
  85 * `Handler.isDefault`
  86 +
  87 returns true if the handler is the default handler.
  88
  89 * `Handler.isIgnore`
  90 +
  91 returns true if the handler is the ignore handler.
  92
  93 * `Handler.simple f`
  94 +
  95 returns a handler that executes `f ()` and does not switch threads.
  96
  97 * `type Mask.t`
  98 +
  99 the type of signal masks, which are sets of blocked signals.
 100
 101 * `Mask.all`
 102 +
 103 a mask of all signals.
 104
 105 * `Mask.allBut l`
 106 +
 107 a mask of all signals except for those in `l`.
 108
 109 * `Mask.block m`
 110 +
 111 blocks all signals in `m`.
 112
 113 * `Mask.getBlocked ()`
 114 +
 115 gets the signal mask `m`, i.e. a signal is blocked if and only if it
 116 is in `m`.
 117
 118 * `Mask.isMember (m, s)`
 119 +
 120 returns true if the signal `s` is in `m`.
 121
 122 * `Mask.none`
 123 +
 124 a mask of no signals.
 125
 126 * `Mask.setBlocked m`
 127 +
 128 sets the signal mask to `m`, i.e. a signal is blocked if and only if
 129 it is in `m`.
 130
 131 * `Mask.some l`
 132 +
 133 a mask of the signals in `l`.
 134
 135 * `Mask.unblock m`
 136 +
 137 unblocks all signals in `m`.
 138
 139 * `getHandler s`
 140 +
 141 returns the current handler for signal `s`.
 142
 143 * `handled ()`
 144 +
 145 returns the signal mask `m` corresponding to the currently handled
 146 signals; i.e., a signal is handled if and only if it is in `m`.
 147
 148 * `prof`
 149 +
 150 `SIGPROF`, the profiling signal.
 151
 152 * `restart`
 153 +
 154 dynamically determines the behavior of interrupted system calls; when
 155 `true`, interrupted system calls are restarted; when `false`,
 156 interrupted system calls raise `OS.SysError`.
 157
 158 * `setHandler (s, h)`
 159 +
 160 sets the handler for signal `s` to `h`.
 161
 162 * `suspend m`
 163 +
 164 temporarily sets the signal mask to `m` and suspends until an unmasked
 165 signal is received and handled, at which point `suspend` resets the
 166 mask and returns.
 167
 168 * `vtalrm`
 169 +
 170 `SIGVTALRM`, the signal for virtual timers.
 171
 172
 173 == Interruptible System Calls ==
 174
 175 Signal handling interacts in a non-trivial way with those functions in
 176 the <:BasisLibrary:Basis Library> that correspond directly to
 177 interruptible system calls (a subset of those functions that may raise
 178 `OS.SysError`).  The desire is that these functions should have
 179 predictable semantics.  The principal concerns are:
 180
 181 1. System calls that are interrupted by signals should, by default, be
 182 restarted; the alternative is to raise
 183 +
 184 [source,sml]
 185 ----
 186 OS.SysError (Posix.Error.errorMsg Posix.Error.intr,
 187              SOME Posix.Error.intr)
 188 ----
 189 +
 190 This behavior is determined dynamically by the value of `Signal.restart`.
 191
 192 2. Signal handlers should always get a chance to run (when outside a
 193 critical region).  If a system call is interrupted by a signal, then
 194 the signal handler will run before the call is restarted or
 195 `OS.SysError` is raised; that is, before the `Signal.restart` check.
 196
 197 3. A system call that must be restarted while in a critical section
 198 will be restarted with the handled signals blocked (and the previously
 199 blocked signals remembered).  This encourages the system call to
 200 complete, allowing the program to make progress towards leaving the
 201 critical section where the signal can be handled.  If the system call
 202 completes, the set of blocked signals are restored to those previously
 203 blocked.