add hg and python

1 files changed, 145 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libqueue.tex b/sys/src/cmd/python/Doc/lib/libqueue.tex
new file mode 100644
index 000000000..95ad47f47
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libqueue.tex
@@ -0,0 +1,145 @@
+
+\section{\module{Queue} ---
+         A synchronized queue class}
+
+\declaremodule{standard}{Queue}
+\modulesynopsis{A synchronized queue class.}
+
+
+The \module{Queue} module implements a multi-producer, multi-consumer
+FIFO queue.  It is especially useful in threads programming when
+information must be exchanged safely between multiple threads.  The
+\class{Queue} class in this module implements all the required locking
+semantics.  It depends on the availability of thread support in
+Python.
+
+The \module{Queue} module defines the following class and exception:
+
+
+\begin{classdesc}{Queue}{maxsize}
+Constructor for the class.  \var{maxsize} is an integer that sets the
+upperbound limit on the number of items that can be placed in the
+queue.  Insertion will block once this size has been reached, until
+queue items are consumed.  If \var{maxsize} is less than or equal to
+zero, the queue size is infinite.
+\end{classdesc}
+
+\begin{excdesc}{Empty}
+Exception raised when non-blocking \method{get()} (or
+\method{get_nowait()}) is called on a \class{Queue} object which is
+empty.
+\end{excdesc}
+
+\begin{excdesc}{Full}
+Exception raised when non-blocking \method{put()} (or
+\method{put_nowait()}) is called on a \class{Queue} object which is
+full.
+\end{excdesc}
+
+\subsection{Queue Objects}
+\label{QueueObjects}
+
+Class \class{Queue} implements queue objects and has the methods
+described below.  This class can be derived from in order to implement
+other queue organizations (e.g. stack) but the inheritable interface
+is not described here.  See the source code for details.  The public
+methods are:
+
+\begin{methoddesc}{qsize}{}
+Return the approximate size of the queue.  Because of multithreading
+semantics, this number is not reliable.
+\end{methoddesc}
+
+\begin{methoddesc}{empty}{}
+Return \code{True} if the queue is empty, \code{False} otherwise.
+Because of multithreading semantics, this is not reliable.
+\end{methoddesc}
+
+\begin{methoddesc}{full}{}
+Return \code{True} if the queue is full, \code{False} otherwise.
+Because of multithreading semantics, this is not reliable.
+\end{methoddesc}
+
+\begin{methoddesc}{put}{item\optional{, block\optional{, timeout}}}
+Put \var{item} into the queue. If optional args \var{block} is true
+and \var{timeout} is None (the default), block if necessary until a
+free slot is available. If \var{timeout} is a positive number, it
+blocks at most \var{timeout} seconds and raises the \exception{Full}
+exception if no free slot was available within that time.
+Otherwise (\var{block} is false), put an item on the queue if a free
+slot is immediately available, else raise the \exception{Full}
+exception (\var{timeout} is ignored in that case).
+
+\versionadded[the timeout parameter]{2.3}
+
+\end{methoddesc}
+
+\begin{methoddesc}{put_nowait}{item}
+Equivalent to \code{put(\var{item}, False)}.
+\end{methoddesc}
+
+\begin{methoddesc}{get}{\optional{block\optional{, timeout}}}
+Remove and return an item from the queue. If optional args
+\var{block} is true and \var{timeout} is None (the default),
+block if necessary until an item is available. If \var{timeout} is
+a positive number, it blocks at most \var{timeout} seconds and raises
+the \exception{Empty} exception if no item was available within that
+time. Otherwise (\var{block} is false), return an item if one is
+immediately available, else raise the \exception{Empty} exception
+(\var{timeout} is ignored in that case).
+
+\versionadded[the timeout parameter]{2.3}
+
+\end{methoddesc}
+
+\begin{methoddesc}{get_nowait}{}
+Equivalent to \code{get(False)}.
+\end{methoddesc}
+
+Two methods are offered to support tracking whether enqueued tasks have
+been fully processed by daemon consumer threads.
+
+\begin{methoddesc}{task_done}{}
+Indicate that a formerly enqueued task is complete.  Used by queue consumer
+threads.  For each \method{get()} used to fetch a task, a subsequent call to
+\method{task_done()} tells the queue that the processing on the task is complete.
+
+If a \method{join()} is currently blocking, it will resume when all items
+have been processed (meaning that a \method{task_done()} call was received
+for every item that had been \method{put()} into the queue).
+
+Raises a \exception{ValueError} if called more times than there were items
+placed in the queue.
+\versionadded{2.5}
+\end{methoddesc}
+
+\begin{methoddesc}{join}{}
+Blocks until all items in the queue have been gotten and processed.
+
+The count of unfinished tasks goes up whenever an item is added to the
+queue. The count goes down whenever a consumer thread calls \method{task_done()}
+to indicate that the item was retrieved and all work on it is complete.
+When the count of unfinished tasks drops to zero, join() unblocks.
+\versionadded{2.5}
+\end{methoddesc}
+
+Example of how to wait for enqueued tasks to be completed:
+
+\begin{verbatim}
+    def worker(): 
+        while True: 
+            item = q.get() 
+            do_work(item) 
+            q.task_done() 
+
+    q = Queue() 
+    for i in range(num_worker_threads): 
+         t = Thread(target=worker)
+         t.setDaemon(True)
+         t.start() 
+
+    for item in source():
+        q.put(item) 
+
+    q.join()       # block until all tasks are done
+\end{verbatim}