| \section{\module{signal} --- |
| Set handlers for asynchronous events.} |
| \declaremodule{builtin}{signal} |
| |
| |
| \modulesynopsis{Set handlers for asynchronous events.} |
| |
| This module provides mechanisms to use signal handlers in Python. |
| Some general rules for working with signals and their handlers: |
| |
| \begin{itemize} |
| |
| \item |
| A handler for a particular signal, once set, remains installed until |
| it is explicitly reset (i.e. Python emulates the BSD style interface |
| regardless of the underlying implementation), with the exception of |
| the handler for \constant{SIGCHLD}, which follows the underlying |
| implementation. |
| |
| \item |
| There is no way to ``block'' signals temporarily from critical |
| sections (since this is not supported by all \UNIX{} flavors). |
| |
| \item |
| Although Python signal handlers are called asynchronously as far as |
| the Python user is concerned, they can only occur between the |
| ``atomic'' instructions of the Python interpreter. This means that |
| signals arriving during long calculations implemented purely in \C{} |
| (e.g.\ regular expression matches on large bodies of text) may be |
| delayed for an arbitrary amount of time. |
| |
| \item |
| When a signal arrives during an I/O operation, it is possible that the |
| I/O operation raises an exception after the signal handler returns. |
| This is dependent on the underlying \UNIX{} system's semantics regarding |
| interrupted system calls. |
| |
| \item |
| Because the \C{} signal handler always returns, it makes little sense to |
| catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}. |
| |
| \item |
| Python installs a small number of signal handlers by default: |
| \constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be |
| reported as ordinary Python exceptions) and \constant{SIGINT} is translated |
| into a \exception{KeyboardInterrupt} exception. All of these can be |
| overridden. |
| |
| \item |
| Some care must be taken if both signals and threads are used in the |
| same program. The fundamental thing to remember in using signals and |
| threads simultaneously is:\ always perform \function{signal()} operations |
| in the main thread of execution. Any thread can perform an |
| \function{alarm()}, \function{getsignal()}, or \function{pause()}; |
| only the main thread can set a new signal handler, and the main thread |
| will be the only one to receive signals (this is enforced by the |
| Python \module{signal} module, even if the underlying thread |
| implementation supports sending signals to individual threads). This |
| means that signals can't be used as a means of inter-thread |
| communication. Use locks instead. |
| |
| \end{itemize} |
| |
| The variables defined in the \module{signal} module are: |
| |
| \begin{datadesc}{SIG_DFL} |
| This is one of two standard signal handling options; it will simply |
| perform the default function for the signal. For example, on most |
| systems the default action for \constant{SIGQUIT} is to dump core |
| and exit, while the default action for \constant{SIGCLD} is to |
| simply ignore it. |
| \end{datadesc} |
| |
| \begin{datadesc}{SIG_IGN} |
| This is another standard signal handler, which will simply ignore |
| the given signal. |
| \end{datadesc} |
| |
| \begin{datadesc}{SIG*} |
| All the signal numbers are defined symbolically. For example, the |
| hangup signal is defined as \constant{signal.SIGHUP}; the variable names |
| are identical to the names used in C programs, as found in |
| \code{<signal.h>}. |
| The \UNIX{} man page for `\cfunction{signal()}' lists the existing |
| signals (on some systems this is \manpage{signal}{2}, on others the |
| list is in \manpage{signal}{7}). |
| Note that not all systems define the same set of signal names; only |
| those names defined by the system are defined by this module. |
| \end{datadesc} |
| |
| \begin{datadesc}{NSIG} |
| One more than the number of the highest signal number. |
| \end{datadesc} |
| |
| The \module{signal} module defines the following functions: |
| |
| \begin{funcdesc}{alarm}{time} |
| If \var{time} is non-zero, this function requests that a |
| \constant{SIGALRM} signal be sent to the process in \var{time} seconds. |
| Any previously scheduled alarm is canceled (i.e.\ only one alarm can |
| be scheduled at any time). The returned value is then the number of |
| seconds before any previously set alarm was to have been delivered. |
| If \var{time} is zero, no alarm id scheduled, and any scheduled |
| alarm is canceled. The return value is the number of seconds |
| remaining before a previously scheduled alarm. If the return value |
| is zero, no alarm is currently scheduled. (See the \UNIX{} man page |
| \manpage{alarm}{2}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getsignal}{signalnum} |
| Return the current signal handler for the signal \var{signalnum}. |
| The returned value may be a callable Python object, or one of the |
| special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or |
| \constant{None}. Here, \constant{signal.SIG_IGN} means that the |
| signal was previously ignored, \constant{signal.SIG_DFL} means that the |
| default way of handling the signal was previously in use, and |
| \code{None} means that the previous signal handler was not installed |
| from Python. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{pause}{} |
| Cause the process to sleep until a signal is received; the |
| appropriate handler will then be called. Returns nothing. (See the |
| \UNIX{} man page \manpage{signal}{2}.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{signal}{signalnum, handler} |
| Set the handler for signal \var{signalnum} to the function |
| \var{handler}. \var{handler} can be a callable Python object |
| taking two arguments (see below), or |
| one of the special values \constant{signal.SIG_IGN} or |
| \constant{signal.SIG_DFL}. The previous signal handler will be returned |
| (see the description of \function{getsignal()} above). (See the |
| \UNIX{} man page \manpage{signal}{2}.) |
| |
| When threads are enabled, this function can only be called from the |
| main thread; attempting to call it from other threads will cause a |
| \exception{ValueError} exception to be raised. |
| |
| The \var{handler} is called with two arguments: the signal number |
| and the current stack frame (\code{None} or a frame object; see the |
| reference manual for a description of frame objects). |
| \obindex{frame} |
| \end{funcdesc} |
| |
| \subsection{Example} |
| \nodename{Signal Example} |
| |
| Here is a minimal example program. It uses the \function{alarm()} |
| function to limit the time spent waiting to open a file; this is |
| useful if the file is for a serial device that may not be turned on, |
| which would normally cause the \function{os.open()} to hang |
| indefinitely. The solution is to set a 5-second alarm before opening |
| the file; if the operation takes too long, the alarm signal will be |
| sent, and the handler raises an exception. |
| |
| \begin{verbatim} |
| import signal, os, FCNTL |
| |
| def handler(signum, frame): |
| print 'Signal handler called with signal', signum |
| raise IOError, "Couldn't open device!" |
| |
| # Set the signal handler and a 5-second alarm |
| signal.signal(signal.SIGALRM, handler) |
| signal.alarm(5) |
| |
| # This open() may hang indefinitely |
| fd = os.open('/dev/ttyS0', FCNTL.O_RDWR) |
| |
| signal.alarm(0) # Disable the alarm |
| \end{verbatim} |