diff options
Diffstat (limited to 'Doc/libsignal.tex')
-rw-r--r-- | Doc/libsignal.tex | 142 |
1 files changed, 0 insertions, 142 deletions
diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex deleted file mode 100644 index 49eb62e..0000000 --- a/Doc/libsignal.tex +++ /dev/null @@ -1,142 +0,0 @@ -\section{Built-in Module \module{signal}} -\label{module-signal} - -\bimodindex{signal} -This module provides mechanisms to use signal handlers in Python. -Some general rules for working with signals 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 - \file{<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 any callable Python object, 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} |