175 lines
7.0 KiB
TeX
175 lines
7.0 KiB
TeX
\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), \constant{SIGINT} is translated
|
|
into a \exception{KeyboardInterrupt} exception, and \constant{SIGTERM} is
|
|
caught so that necessary cleanup (especially \code{sys.exitfunc}) can
|
|
be performed before actually terminating. 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 interthread
|
|
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}
|