summaryrefslogtreecommitdiffstats
path: root/Doc/libsignal.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/libsignal.tex')
-rw-r--r--Doc/libsignal.tex142
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}