add hg and python

1 files changed, 174 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libsignal.tex b/sys/src/cmd/python/Doc/lib/libsignal.tex
new file mode 100644
index 000000000..cfdb4dde1
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libsignal.tex
@@ -0,0 +1,174 @@
+\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 (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
+(such as 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) and \constant{SIGINT} is translated
+into a \exception{KeyboardInterrupt} exception.  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 inter-thread
+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 (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 is 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}.)
+  Availability: \UNIX.
+\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.  Not on
+  Windows. (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;
+  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).
+\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}