added lots of useful info

Doc/lib/libsignal.tex

@@ -1,17 +1,57 @@
 \section{Built-in Module \sectcode{signal}}
 
 \bimodindex{signal}
-This module provides mechanisms to write signal handlers in Python.
+This module provides mechanisms to use signal handlers in Python.
+Some general rules for working with signals handlers:
 
-{\bf Warning:} Some care must be taken if both signals and threads
+\begin{itemize}
-will be used in the same program.  The fundamental thing to remember
+
-in using signals and threads simultaneously is: always perform
+\item
-\code{signal()} operations in the main thread of execution.  Any
+A handler for a particular signal, once set, remains installed until
-thread can perform a \code{alarm()}, \code{getsignal()}, or
+it is explicitly reset (i.e. Python uses the BSD style interface).
-\code{pause()}; only the main thread can set a new signal handler, and
+
-the main thread will be the only one to receive signals.  This means
+\item
-that signals can't be used as a means of interthread communication.
+There is no way to ``block'' signals temporarily from critical
-Use locks instead.
+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 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 \code{SIGFPE} or \code{SIGSEGV}.
+
+\item
+Python installs a small number of signal handlers by default:
+\code{SIGPIPE} is ignored (so write errors on pipes and sockets can be
+reported as ordinary Python exceptions), \code{SIGINT} is translated
+into a \code{KeyboardInterrupt} exception, and \code{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 \code{signal()} operations
+in the main thread of execution.  Any thread can perform a
+\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
+thread can set a new signal handler, and the main thread will be the
+only one to receive signals.  This means that signals can't be used as
+a means of interthread communication.  Use locks instead.
+
+\end{itemize}
 
 The variables defined in the signal module are:
 
@@ -40,6 +80,10 @@ The variables defined in the signal module are:
   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 signal module defines the following functions:
 
 \begin{funcdesc}{alarm}{time}
@@ -58,7 +102,11 @@ The signal module defines the following functions:
 \begin{funcdesc}{getsignal}{signalnum}
   Returns the current signal handler for the signal \var{signalnum}.
   The returned value may be a callable Python object, or one of the
-  special values \code{signal.SIG_IGN} or \code{signal.SIG_DFL}.
+  special values \code{signal.SIG_IGN}, \code{signal.SIG_DFL} or
+  \code{None}.  Here, \code{signal.SIG_IGN} means that the signal was
+  previously ignored, \code{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}{}
@@ -71,10 +119,11 @@ The signal module defines the following functions:
   Sets 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 \code{signal.SIG_IGN} or
-  \code{signal.SIG_DFL}.  The previous signal handler will be
+  \code{signal.SIG_DFL}.  The previous signal handler will be returned
-  returned.  (See the UNIX man page \code{signal(2)}.)
+  (see the description of \code{getsignal()} above).  (See the UNIX
+  man page \code{signal(2)}.)
 
-  If threads are enabled, this function can only be called from the
+  When threads are enabled, this function can only be called from the
   main thread; attempting to call it from other threads will cause a
   \code{ValueError} exception will be raised.
 \end{funcdesc}

Doc/libsignal.tex

@@ -1,17 +1,57 @@
 \section{Built-in Module \sectcode{signal}}
 
 \bimodindex{signal}
-This module provides mechanisms to write signal handlers in Python.
+This module provides mechanisms to use signal handlers in Python.
+Some general rules for working with signals handlers:
 
-{\bf Warning:} Some care must be taken if both signals and threads
+\begin{itemize}
-will be used in the same program.  The fundamental thing to remember
+
-in using signals and threads simultaneously is: always perform
+\item
-\code{signal()} operations in the main thread of execution.  Any
+A handler for a particular signal, once set, remains installed until
-thread can perform a \code{alarm()}, \code{getsignal()}, or
+it is explicitly reset (i.e. Python uses the BSD style interface).
-\code{pause()}; only the main thread can set a new signal handler, and
+
-the main thread will be the only one to receive signals.  This means
+\item
-that signals can't be used as a means of interthread communication.
+There is no way to ``block'' signals temporarily from critical
-Use locks instead.
+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 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 \code{SIGFPE} or \code{SIGSEGV}.
+
+\item
+Python installs a small number of signal handlers by default:
+\code{SIGPIPE} is ignored (so write errors on pipes and sockets can be
+reported as ordinary Python exceptions), \code{SIGINT} is translated
+into a \code{KeyboardInterrupt} exception, and \code{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 \code{signal()} operations
+in the main thread of execution.  Any thread can perform a
+\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
+thread can set a new signal handler, and the main thread will be the
+only one to receive signals.  This means that signals can't be used as
+a means of interthread communication.  Use locks instead.
+
+\end{itemize}
 
 The variables defined in the signal module are:
 
@@ -40,6 +80,10 @@ The variables defined in the signal module are:
   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 signal module defines the following functions:
 
 \begin{funcdesc}{alarm}{time}
@@ -58,7 +102,11 @@ The signal module defines the following functions:
 \begin{funcdesc}{getsignal}{signalnum}
   Returns the current signal handler for the signal \var{signalnum}.
   The returned value may be a callable Python object, or one of the
-  special values \code{signal.SIG_IGN} or \code{signal.SIG_DFL}.
+  special values \code{signal.SIG_IGN}, \code{signal.SIG_DFL} or
+  \code{None}.  Here, \code{signal.SIG_IGN} means that the signal was
+  previously ignored, \code{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}{}
@@ -71,10 +119,11 @@ The signal module defines the following functions:
   Sets 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 \code{signal.SIG_IGN} or
-  \code{signal.SIG_DFL}.  The previous signal handler will be
+  \code{signal.SIG_DFL}.  The previous signal handler will be returned
-  returned.  (See the UNIX man page \code{signal(2)}.)
+  (see the description of \code{getsignal()} above).  (See the UNIX
+  man page \code{signal(2)}.)
 
-  If threads are enabled, this function can only be called from the
+  When threads are enabled, this function can only be called from the
   main thread; attempting to call it from other threads will cause a
   \code{ValueError} exception will be raised.
 \end{funcdesc}