Doc/lib/libsignal.tex

   1 \section{\module{signal} ---
   2          Set handlers for asynchronous events}
   3
   4 \declaremodule{builtin}{signal}
   5 \modulesynopsis{Set handlers for asynchronous events.}
   6
   7
   8 This module provides mechanisms to use signal handlers in Python.
   9 Some general rules for working with signals and their handlers:
  10
  11 \begin{itemize}
  12
  13 \item
  14 A handler for a particular signal, once set, remains installed until
  15 it is explicitly reset (Python emulates the BSD style interface
  16 regardless of the underlying implementation), with the exception of
  17 the handler for \constant{SIGCHLD}, which follows the underlying
  18 implementation.
  19
  20 \item
  21 Although Python signal handlers are called asynchronously as far as
  22 the Python user is concerned, they can only occur between the
  23 ``atomic'' instructions of the Python interpreter.  This means that
  24 signals arriving during long calculations implemented purely in C
  25 (such as regular expression matches on large bodies of text) may be
  26 delayed for an arbitrary amount of time.
  27
  28 \item
  29 When a signal arrives during an I/O operation, it is possible that the
  30 I/O operation raises an exception after the signal handler returns.
  31 This is dependent on the underlying \UNIX{} system's semantics regarding
  32 interrupted system calls.
  33
  34 \item
  35 Because the \C{} signal handler always returns, it makes little sense to
  36 catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}.
  37
  38 \item
  39 Python installs a small number of signal handlers by default:
  40 \constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be
  41 reported as ordinary Python exceptions) and \constant{SIGINT} is translated
  42 into a \exception{KeyboardInterrupt} exception.  All of these can be
  43 overridden.
  44
  45 \item
  46 Some care must be taken if both signals and threads are used in the
  47 same program.  The fundamental thing to remember in using signals and
  48 threads simultaneously is:\ always perform \function{signal()} operations
  49 in the main thread of execution.  Any thread can perform an
  50 \function{alarm()}, \function{getsignal()}, or \function{pause()};
  51 only the main thread can set a new signal handler, and the main thread
  52 will be the only one to receive signals (this is enforced by the
  53 Python \module{signal} module, even if the underlying thread
  54 implementation supports sending signals to individual threads).  This
  55 means that signals can't be used as a means of inter-thread
  56 communication.  Use locks instead.
  57
  58 \end{itemize}
  59
  60 The variables defined in the \module{signal} module are:
  61
  62 \begin{datadesc}{SIG_DFL}
  63   This is one of two standard signal handling options; it will simply
  64   perform the default function for the signal.  For example, on most
  65   systems the default action for \constant{SIGQUIT} is to dump core
  66   and exit, while the default action for \constant{SIGCLD} is to
  67   simply ignore it.
  68 \end{datadesc}
  69
  70 \begin{datadesc}{SIG_IGN}
  71   This is another standard signal handler, which will simply ignore
  72   the given signal.
  73 \end{datadesc}
  74
  75 \begin{datadesc}{SIG*}
  76   All the signal numbers are defined symbolically.  For example, the
  77   hangup signal is defined as \constant{signal.SIGHUP}; the variable names
  78   are identical to the names used in C programs, as found in
  79   \code{<signal.h>}.
  80   The \UNIX{} man page for `\cfunction{signal()}' lists the existing
  81   signals (on some systems this is \manpage{signal}{2}, on others the
  82   list is in \manpage{signal}{7}).
  83   Note that not all systems define the same set of signal names; only
  84   those names defined by the system are defined by this module.
  85 \end{datadesc}
  86
  87 \begin{datadesc}{NSIG}
  88   One more than the number of the highest signal number.
  89 \end{datadesc}
  90
  91 \begin{datadesc}{SIG_BLOCK}
  92 \end{datadesc}
  93 \begin{datadesc}{SIG_UNBLOCK}
  94 \end{datadesc}
  95 \begin{datadesc}{SIG_SETMASK}
  96   These constants are for use as the first parameter of the
  97   \function{sigprocmask} function described below.
  98 \end{datadesc}
  99
 100
 101 The \module{signal} module defines the following functions:
 102
 103 \begin{funcdesc}{alarm}{time}
 104   If \var{time} is non-zero, this function requests that a
 105   \constant{SIGALRM} signal be sent to the process in \var{time} seconds.
 106   Any previously scheduled alarm is canceled (only one alarm can
 107   be scheduled at any time).  The returned value is then the number of
 108   seconds before any previously set alarm was to have been delivered.
 109   If \var{time} is zero, no alarm id scheduled, and any scheduled
 110   alarm is canceled.  The return value is the number of seconds
 111   remaining before a previously scheduled alarm.  If the return value
 112   is zero, no alarm is currently scheduled.  (See the \UNIX{} man page
 113   \manpage{alarm}{2}.)
 114   Availability: \UNIX.
 115 \end{funcdesc}
 116
 117 \begin{funcdesc}{getsignal}{signalnum}
 118   Return the current signal handler for the signal \var{signalnum}.
 119   The returned value may be a callable Python object, or one of the
 120   special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or
 121   \constant{None}.  Here, \constant{signal.SIG_IGN} means that the
 122   signal was previously ignored, \constant{signal.SIG_DFL} means that the
 123   default way of handling the signal was previously in use, and
 124   \code{None} means that the previous signal handler was not installed
 125   from Python.
 126 \end{funcdesc}
 127
 128 \begin{funcdesc}{pause}{}
 129   Cause the process to sleep until a signal is received; the
 130   appropriate handler will then be called.  Returns nothing.  Not on
 131   Windows. (See the \UNIX{} man page \manpage{signal}{2}.)
 132 \end{funcdesc}
 133
 134 \begin{funcdesc}{signal}{signalnum, handler}
 135   Set the handler for signal \var{signalnum} to the function
 136   \var{handler}.  \var{handler} can be a callable Python object
 137   taking two arguments (see below), or
 138   one of the special values \constant{signal.SIG_IGN} or
 139   \constant{signal.SIG_DFL}.  The previous signal handler will be returned
 140   (see the description of \function{getsignal()} above).  (See the
 141   \UNIX{} man page \manpage{signal}{2}.)
 142
 143   When threads are enabled, this function can only be called from the
 144   main thread; attempting to call it from other threads will cause a
 145   \exception{ValueError} exception to be raised.
 146
 147   The \var{handler} is called with two arguments: the signal number
 148   and the current stack frame (\code{None} or a frame object; see the
 149   reference manual for a description of frame objects).
 150 \obindex{frame}
 151 \end{funcdesc}
 152
 153 The following functions are supported if your platform does.  Most
 154 modern \UNIX-alikes now do.
 155
 156 \begin{funcdesc}{sigpending}{}
 157   Return the set of pending signals, i.e. a list containing the
 158   numbers of those signals that have been raised while blocked.
 159   \versionadded{2.3}
 160 \end{funcdesc}
 161
 162 \begin{funcdesc}{sigprocmask}{how, sigset}
 163   Change the list of currently blocked signals.  The parameter
 164   \var{how} should be one of \constant{SIG_BLOCK},
 165   \constant{SIG_UNBLOCK} or \constant{SIG_SETMASK} and \var{sigset}
 166   should be a sequence of signal numbers.  The behaviour of the call
 167   depends on the value of \var{how}:
 168
 169   \begin{tableii}{l|l}{textrm}{Value of \var{how}}{Behaviour of call}
 170     \lineii{\constant{SIG_BLOCK}}
 171            {The set of blocked signals is the union of the current set
 172             and \var{sigset}.}
 173     \lineii{\constant{SIG_UNBLOCK}}
 174            {The signals in \var{sigset} are removed from the current
 175             set of blocked signals.  It is legal to attempt to unblock
 176             a signal which is not blocked.}
 177     \lineii{\constant{SIG_SETMASK}}
 178            {The set of blocked signals is set to the \var{sigset}.}
 179   \end{tableii}
 180
 181   A list contating the numbers of the previously blocked signals is
 182   returned.
 183   \versionadded{2.3}
 184 \end{funcdesc}
 185
 186 \begin{funcdesc}{sigsuspend}{sigset}
 187   Temporarily replace the signal mask with \var{sigset} (which should
 188   be a sequnce of signal numbers) and suspend the process until a
 189   signal is received.
 190   \versionadded{2.3}
 191 \end{funcdesc}
 192
 193 \subsection{Example}
 194 \nodename{Signal Example}
 195
 196 Here is a minimal example program. It uses the \function{alarm()}
 197 function to limit the time spent waiting to open a file; this is
 198 useful if the file is for a serial device that may not be turned on,
 199 which would normally cause the \function{os.open()} to hang
 200 indefinitely.  The solution is to set a 5-second alarm before opening
 201 the file; if the operation takes too long, the alarm signal will be
 202 sent, and the handler raises an exception.
 203
 204 \begin{verbatim}
 205 import signal, os
 206
 207 def handler(signum, frame):
 208     print 'Signal handler called with signal', signum
 209     raise IOError, "Couldn't open device!"
 210
 211 # Set the signal handler and a 5-second alarm
 212 signal.signal(signal.SIGALRM, handler)
 213 signal.alarm(5)
 214
 215 # This open() may hang indefinitely
 216 fd = os.open('/dev/ttyS0', os.O_RDWR)
 217
 218 signal.alarm(0)          # Disable the alarm
 219 \end{verbatim}