cpython/Doc/lib/libsignal.tex

175 lines
7.0 KiB
TeX
Raw Normal View History

\section{\module{signal} ---
Set handlers for asynchronous events}
\declaremodule{builtin}{signal}
\modulesynopsis{Set handlers for asynchronous events.}
1995-02-07 10:37:02 -04:00
1995-02-15 11:52:32 -04:00
This module provides mechanisms to use signal handlers in Python.
Some general rules for working with signals and their handlers:
1995-02-15 11:52:32 -04:00
\begin{itemize}
\item
A handler for a particular signal, once set, remains installed until
it is explicitly reset (Python emulates the BSD style interface
1996-02-12 19:18:51 -04:00
regardless of the underlying implementation), with the exception of
the handler for \constant{SIGCHLD}, which follows the underlying
1996-02-12 19:18:51 -04:00
implementation.
1995-02-15 11:52:32 -04:00
\item
There is no way to ``block'' signals temporarily from critical
sections (since this is not supported by all \UNIX{} flavors).
1995-02-15 11:52:32 -04:00
\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
(such as regular expression matches on large bodies of text) may be
delayed for an arbitrary amount of time.
1995-02-15 11:52:32 -04:00
\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.
1995-03-13 06:03:32 -04:00
This is dependent on the underlying \UNIX{} system's semantics regarding
1995-02-15 11:52:32 -04:00
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}.
1995-02-15 11:52:32 -04:00
\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
1995-02-15 11:52:32 -04:00
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
1995-03-13 06:03:32 -04:00
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.
1995-02-15 11:52:32 -04:00
\end{itemize}
1995-02-07 10:37:02 -04:00
The variables defined in the \module{signal} module are:
1995-02-07 10:37:02 -04:00
\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.
1995-02-07 10:37:02 -04:00
\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
1995-02-07 10:37:02 -04:00
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}).
1995-02-07 10:37:02 -04:00
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}
1995-02-15 11:52:32 -04:00
\begin{datadesc}{NSIG}
One more than the number of the highest signal number.
\end{datadesc}
The \module{signal} module defines the following functions:
1995-02-07 10:37:02 -04:00
\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 (only one alarm can
1995-02-07 10:37:02 -04:00
be scheduled at any time). The returned value is then the number of
seconds before any previously set alarm was to have been delivered.
2006-04-01 03:42:41 -04:00
If \var{time} is zero, no alarm is scheduled, and any scheduled
1995-02-07 10:37:02 -04:00
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}.)
Availability: \UNIX.
1995-02-07 10:37:02 -04:00
\end{funcdesc}
\begin{funcdesc}{getsignal}{signalnum}
1995-03-13 06:03:32 -04:00
Return the current signal handler for the signal \var{signalnum}.
1995-02-07 10:37:02 -04:00
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.
1995-02-07 10:37:02 -04:00
\end{funcdesc}
\begin{funcdesc}{pause}{}
1995-03-13 06:03:32 -04:00
Cause the process to sleep until a signal is received; the
appropriate handler will then be called. Returns nothing. Not on
Windows. (See the \UNIX{} man page \manpage{signal}{2}.)
1995-02-07 10:37:02 -04:00
\end{funcdesc}
\begin{funcdesc}{signal}{signalnum, handler}
1995-03-13 06:03:32 -04:00
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}.)
1995-02-07 10:37:02 -04:00
1995-02-15 11:52:32 -04:00
When threads are enabled, this function can only be called from the
1995-02-07 10:37:02 -04:00
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;
for a description of frame objects, see the reference manual section
on the standard type hierarchy or see the attribute descriptions in
the \refmodule{inspect} module).
1995-02-07 10:37:02 -04:00
\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
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', os.O_RDWR)
signal.alarm(0) # Disable the alarm
\end{verbatim}