| \section{\module{threading} --- |
| Higher-level threading interface} |
| |
| \declaremodule{standard}{threading} |
| \modulesynopsis{Higher-level threading interface.} |
| |
| |
| This module constructs higher-level threading interfaces on top of the |
| lower level \refmodule{thread} module. |
| |
| This module is safe for use with \samp{from threading import *}. It |
| defines the following functions and objects: |
| |
| \begin{funcdesc}{activeCount}{} |
| Return the number of currently active \class{Thread} objects. |
| The returned count is equal to the length of the list returned by |
| \function{enumerate()}. |
| A function that returns the number of currently active threads. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{Condition}{} |
| A factory function that returns a new condition variable object. |
| A condition variable allows one or more threads to wait until they |
| are notified by another thread. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{currentThread}{} |
| Return the current \class{Thread} object, corresponding to the |
| caller's thread of control. If the caller's thread of control was not |
| created through the |
| \module{threading} module, a dummy thread object with limited functionality |
| is returned. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{enumerate}{} |
| Return a list of all currently active \class{Thread} objects. |
| The list includes daemonic threads, dummy thread objects created |
| by \function{currentThread()}, and the main thread. It excludes terminated |
| threads and threads that have not yet been started. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{Event}{} |
| A factory function that returns a new event object. An event |
| manages a flag that can be set to true with the \method{set()} method and |
| reset to false with the \method{clear()} method. The \method{wait()} method blocks |
| until the flag is true. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{Lock}{} |
| A factory function that returns a new primitive lock object. Once |
| a thread has acquired it, subsequent attempts to acquire it block, |
| until it is released; any thread may release it. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{RLock}{} |
| A factory function that returns a new reentrant lock object. |
| A reentrant lock must be released by the thread that acquired it. |
| Once a thread has acquired a reentrant lock, the same thread may |
| acquire it again without blocking; the thread must release it once |
| for each time it has acquired it. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{Semaphore}{} |
| A factory function that returns a new semaphore object. A |
| semaphore manages a counter representing the number of \method{release()} |
| calls minus the number of \method{acquire()} calls, plus an initial value. |
| The \method{acquire()} method blocks if necessary until it can return |
| without making the counter negative. |
| \end{funcdesc} |
| |
| \begin{classdesc*}{Thread}{} |
| A class that represents a thread of control. This class can be safely subclassed in a limited fashion. |
| \end{classdesc*} |
| |
| Detailed interfaces for the objects are documented below. |
| |
| The design of this module is loosely based on Java's threading model. |
| However, where Java makes locks and condition variables basic behavior |
| of every object, they are separate objects in Python. Python's \class{Thread} |
| class supports a subset of the behavior of Java's Thread class; |
| currently, there are no priorities, no thread groups, and threads |
| cannot be destroyed, stopped, suspended, resumed, or interrupted. The |
| static methods of Java's Thread class, when implemented, are mapped to |
| module-level functions. |
| |
| All of the methods described below are executed atomically. |
| |
| |
| \subsection{Lock Objects \label{lock-objects}} |
| |
| A primitive lock is a synchronization primitive that is not owned |
| by a particular thread when locked. In Python, it is currently |
| the lowest level synchronization primitive available, implemented |
| directly by the \refmodule{thread} extension module. |
| |
| A primitive lock is in one of two states, ``locked'' or ``unlocked''. |
| It is created in the unlocked state. It has two basic methods, |
| \method{acquire()} and \method{release()}. When the state is |
| unlocked, \method{acquire()} changes the state to locked and returns |
| immediately. When the state is locked, \method{acquire()} blocks |
| until a call to \method{release()} in another thread changes it to |
| unlocked, then the \method{acquire()} call resets it to locked and |
| returns. The \method{release()} method should only be called in the |
| locked state; it changes the state to unlocked and returns |
| immediately. When more than one thread is blocked in |
| \method{acquire()} waiting for the state to turn to unlocked, only one |
| thread proceeds when a \method{release()} call resets the state to |
| unlocked; which one of the waiting threads proceeds is not defined, |
| and may vary across implementations. |
| |
| All methods are executed atomically. |
| |
| \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} |
| Acquire a lock, blocking or non-blocking. |
| |
| When invoked without arguments, block until the lock is |
| unlocked, then set it to locked, and return. There is no |
| return value in this case. |
| |
| When invoked with the \var{blocking} argument set to true, do the |
| same thing as when called without arguments, and return true. |
| |
| When invoked with the \var{blocking} argument set to false, do not |
| block. If a call without an argument would block, return false |
| immediately; otherwise, do the same thing as when called |
| without arguments, and return true. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{release}{} |
| Release a lock. |
| |
| When the lock is locked, reset it to unlocked, and return. If |
| any other threads are blocked waiting for the lock to become |
| unlocked, allow exactly one of them to proceed. |
| |
| Do not call this method when the lock is unlocked. |
| |
| There is no return value. |
| \end{methoddesc} |
| |
| |
| \subsection{RLock Objects \label{rlock-objects}} |
| |
| A reentrant lock is a synchronization primitive that may be |
| acquired multiple times by the same thread. Internally, it uses |
| the concepts of ``owning thread'' and ``recursion level'' in |
| addition to the locked/unlocked state used by primitive locks. In |
| the locked state, some thread owns the lock; in the unlocked |
| state, no thread owns it. |
| |
| To lock the lock, a thread calls its \method{acquire()} method; this |
| returns once the thread owns the lock. To unlock the lock, a |
| thread calls its \method{release()} method. |
| \method{acquire()}/\method{release()} call pairs may be nested; only |
| the final \method{release()} (the \method{release()} of the outermost |
| pair) resets the lock to unlocked and allows another thread blocked in |
| \method{acquire()} to proceed. |
| |
| \begin{methoddesc}{acquire}{\optional{blocking\code{ = 1}}} |
| Acquire a lock, blocking or non-blocking. |
| |
| When invoked without arguments: if this thread already owns |
| the lock, increment the recursion level by one, and return |
| immediately. Otherwise, if another thread owns the lock, |
| block until the lock is unlocked. Once the lock is unlocked |
| (not owned by any thread), then grab ownership, set the |
| recursion level to one, and return. If more than one thread |
| is blocked waiting until the lock is unlocked, only one at a |
| time will be able to grab ownership of the lock. There is no |
| return value in this case. |
| |
| When invoked with the \var{blocking} argument set to true, do the |
| same thing as when called without arguments, and return true. |
| |
| When invoked with the \var{blocking} argument set to false, do not |
| block. If a call without an argument would block, return false |
| immediately; otherwise, do the same thing as when called |
| without arguments, and return true. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{release}{} |
| Release a lock, decrementing the recursion level. If after the |
| decrement it is zero, reset the lock to unlocked (not owned by any |
| thread), and if any other threads are blocked waiting for the lock to |
| become unlocked, allow exactly one of them to proceed. If after the |
| decrement the recursion level is still nonzero, the lock remains |
| locked and owned by the calling thread. |
| |
| Only call this method when the calling thread owns the lock. |
| Do not call this method when the lock is unlocked. |
| |
| There is no return value. |
| \end{methoddesc} |
| |
| |
| \subsection{Condition Objects \label{condition-objects}} |
| |
| A condition variable is always associated with some kind of lock; |
| this can be passed in or one will be created by default. (Passing |
| one in is useful when several condition variables must share the |
| same lock.) |
| |
| A condition variable has \method{acquire()} and \method{release()} |
| methods that call the corresponding methods of the associated lock. |
| It also has a \method{wait()} method, and \method{notify()} and |
| \method{notifyAll()} methods. These three must only be called when |
| the calling thread has acquired the lock. |
| |
| The \method{wait()} method releases the lock, and then blocks until it |
| is awakened by a \method{notify()} or \method{notifyAll()} call for |
| the same condition variable in another thread. Once awakened, it |
| re-acquires the lock and returns. It is also possible to specify a |
| timeout. |
| |
| The \method{notify()} method wakes up one of the threads waiting for |
| the condition variable, if any are waiting. The \method{notifyAll()} |
| method wakes up all threads waiting for the condition variable. |
| |
| Note: the \method{notify()} and \method{notifyAll()} methods don't |
| release the lock; this means that the thread or threads awakened will |
| not return from their \method{wait()} call immediately, but only when |
| the thread that called \method{notify()} or \method{notifyAll()} |
| finally relinquishes ownership of the lock. |
| |
| Tip: the typical programming style using condition variables uses the |
| lock to synchronize access to some shared state; threads that are |
| interested in a particular change of state call \method{wait()} |
| repeatedly until they see the desired state, while threads that modify |
| the state call \method{notify()} or \method{notifyAll()} when they |
| change the state in such a way that it could possibly be a desired |
| state for one of the waiters. For example, the following code is a |
| generic producer-consumer situation with unlimited buffer capacity: |
| |
| \begin{verbatim} |
| # Consume one item |
| cv.acquire() |
| while not an_item_is_available(): |
| cv.wait() |
| get_an_available_item() |
| cv.release() |
| |
| # Produce one item |
| cv.acquire() |
| make_an_item_available() |
| cv.notify() |
| cv.release() |
| \end{verbatim} |
| |
| To choose between \method{notify()} and \method{notifyAll()}, consider |
| whether one state change can be interesting for only one or several |
| waiting threads. E.g. in a typical producer-consumer situation, |
| adding one item to the buffer only needs to wake up one consumer |
| thread. |
| |
| \begin{classdesc}{Condition}{\optional{lock}} |
| If the \var{lock} argument is given and not \code{None}, it must be a |
| \class{Lock} or \class{RLock} object, and it is used as the underlying |
| lock. Otherwise, a new \class{RLock} object is created and used as |
| the underlying lock. |
| \end{classdesc} |
| |
| \begin{methoddesc}{acquire}{*args} |
| Acquire the underlying lock. |
| This method calls the corresponding method on the underlying |
| lock; the return value is whatever that method returns. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{release}{} |
| Release the underlying lock. |
| This method calls the corresponding method on the underlying |
| lock; there is no return value. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{wait}{\optional{timeout}} |
| Wait until notified or until a timeout occurs. |
| This must only be called when the calling thread has acquired the |
| lock. |
| |
| This method releases the underlying lock, and then blocks until it is |
| awakened by a \method{notify()} or \method{notifyAll()} call for the |
| same condition variable in another thread, or until the optional |
| timeout occurs. Once awakened or timed out, it re-acquires the lock |
| and returns. |
| |
| When the \var{timeout} argument is present and not \code{None}, it |
| should be a floating point number specifying a timeout for the |
| operation in seconds (or fractions thereof). |
| |
| When the underlying lock is an \class{RLock}, it is not released using |
| its \method{release()} method, since this may not actually unlock the |
| lock when it was acquired multiple times recursively. Instead, an |
| internal interface of the \class{RLock} class is used, which really |
| unlocks it even when it has been recursively acquired several times. |
| Another internal interface is then used to restore the recursion level |
| when the lock is reacquired. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{notify}{} |
| Wake up a thread waiting on this condition, if any. |
| This must only be called when the calling thread has acquired the |
| lock. |
| |
| This method wakes up one of the threads waiting for the condition |
| variable, if any are waiting; it is a no-op if no threads are waiting. |
| |
| The current implementation wakes up exactly one thread, if any are |
| waiting. However, it's not safe to rely on this behavior. A future, |
| optimized implementation may occasionally wake up more than one |
| thread. |
| |
| Note: the awakened thread does not actually return from its |
| \method{wait()} call until it can reacquire the lock. Since |
| \method{notify()} does not release the lock, its caller should. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{notifyAll}{} |
| Wake up all threads waiting on this condition. This method acts like |
| \method{notify()}, but wakes up all waiting threads instead of one. |
| \end{methoddesc} |
| |
| |
| \subsection{Semaphore Objects \label{semaphore-objects}} |
| |
| This is one of the oldest synchronization primitives in the history of |
| computer science, invented by the early Dutch computer scientist |
| Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of |
| \method{acquire()} and \method{release()}). |
| |
| A semaphore manages an internal counter which is decremented by each |
| \method{acquire()} call and incremented by each \method{release()} |
| call. The counter can never go below zero; when \method{acquire()} |
| finds that it is zero, it blocks, waiting until some other thread |
| calls \method{release()}. |
| |
| \begin{classdesc}{Semaphore}{\optional{value}} |
| The optional argument gives the initial value for the internal |
| counter; it defaults to \code{1}. |
| \end{classdesc} |
| |
| \begin{methoddesc}{acquire}{\optional{blocking}} |
| Acquire a semaphore. |
| |
| When invoked without arguments: if the internal counter is larger than |
| zero on entry, decrement it by one and return immediately. If it is |
| zero on entry, block, waiting until some other thread has called |
| \method{release()} to make it larger than zero. This is done with |
| proper interlocking so that if multiple \method{acquire()} calls are |
| blocked, \method{release()} will wake exactly one of them up. The |
| implementation may pick one at random, so the order in which blocked |
| threads are awakened should not be relied on. There is no return |
| value in this case. |
| |
| When invoked with \var{blocking} set to true, do the same thing as |
| when called without arguments, and return true. |
| |
| When invoked with \var{blocking} set to false, do not block. If a |
| call without an argument would block, return false immediately; |
| otherwise, do the same thing as when called without arguments, and |
| return true. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{release}{} |
| Release a semaphore, |
| incrementing the internal counter by one. When it was zero on |
| entry and another thread is waiting for it to become larger |
| than zero again, wake up that thread. |
| \end{methoddesc} |
| |
| |
| \subsection{Event Objects \label{event-objects}} |
| |
| This is one of the simplest mechanisms for communication between |
| threads: one thread signals an event and one or more other threads |
| are waiting for it. |
| |
| An event object manages an internal flag that can be set to true with |
| the \method{set()} method and reset to false with the \method{clear()} method. The |
| \method{wait()} method blocks until the flag is true. |
| |
| |
| \begin{classdesc}{Event}{} |
| The internal flag is initially false. |
| \end{classdesc} |
| |
| \begin{methoddesc}{isSet}{} |
| Return true if and only if the internal flag is true. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{set}{} |
| Set the internal flag to true. |
| All threads waiting for it to become true are awakened. |
| Threads that call \method{wait()} once the flag is true will not block |
| at all. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{clear}{} |
| Reset the internal flag to false. |
| Subsequently, threads calling \method{wait()} will block until \method{set()} is |
| called to set the internal flag to true again. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{wait}{\optional{timeout}} |
| Block until the internal flag is true. |
| If the internal flag is true on entry, return immediately. Otherwise, |
| block until another thread calls \method{set()} to set the flag to |
| true, or until the optional timeout occurs. |
| |
| When the timeout argument is present and not \code{None}, it should be a |
| floating point number specifying a timeout for the operation in |
| seconds (or fractions thereof). |
| \end{methoddesc} |
| |
| |
| \subsection{Thread Objects \label{thread-objects}} |
| |
| This class represents an activity that is run in a separate thread |
| of control. There are two ways to specify the activity: by |
| passing a callable object to the constructor, or by overriding the |
| \method{run()} method in a subclass. No other methods (except for the |
| constructor) should be overridden in a subclass. In other words, |
| \emph{only} override the \method{__init__()} and \method{run()} |
| methods of this class. |
| |
| Once a thread object is created, its activity must be started by |
| calling the thread's \method{start()} method. This invokes the |
| \method{run()} method in a separate thread of control. |
| |
| Once the thread's activity is started, the thread is considered |
| 'alive' and 'active' (these concepts are almost, but not quite |
| exactly, the same; their definition is intentionally somewhat |
| vague). It stops being alive and active when its \method{run()} |
| method terminates -- either normally, or by raising an unhandled |
| exception. The \method{isAlive()} method tests whether the thread is |
| alive. |
| |
| Other threads can call a thread's \method{join()} method. This blocks |
| the calling thread until the thread whose \method{join()} method is |
| called is terminated. |
| |
| A thread has a name. The name can be passed to the constructor, |
| set with the \method{setName()} method, and retrieved with the |
| \method{getName()} method. |
| |
| A thread can be flagged as a ``daemon thread''. The significance |
| of this flag is that the entire Python program exits when only |
| daemon threads are left. The initial value is inherited from the |
| creating thread. The flag can be set with the \method{setDaemon()} |
| method and retrieved with the \method{isDaemon()} method. |
| |
| There is a ``main thread'' object; this corresponds to the |
| initial thread of control in the Python program. It is not a |
| daemon thread. |
| |
| There is the possibility that ``dummy thread objects'' are |
| created. These are thread objects corresponding to ``alien |
| threads''. These are threads of control started outside the |
| threading module, such as directly from C code. Dummy thread objects |
| have limited functionality; they are always considered alive, |
| active, and daemonic, and cannot be \method{join()}ed. They are never |
| deleted, since it is impossible to detect the termination of alien |
| threads. |
| |
| |
| \begin{classdesc}{Thread}{group=None, target=None, name=None, |
| args=(), kwargs=\{\}} |
| This constructor should always be called with keyword |
| arguments. Arguments are: |
| |
| \var{group} should be \code{None}; reserved for future extension when |
| a \class{ThreadGroup} class is implemented. |
| |
| \var{target} is the callable object to be invoked by the |
| \method{run()} method. Defaults to \code{None}, meaning nothing is |
| called. |
| |
| \var{name} is the thread name. By default, a unique name is |
| constructed of the form ``Thread-\var{N}'' where \var{N} is a small |
| decimal number. |
| |
| \var{args} is the argument tuple for the target invocation. Defaults |
| to \code{()}. |
| |
| \var{kwargs} is a dictionary of keyword arguments for the target |
| invocation. Defaults to \code{\{\}}. |
| |
| If the subclass overrides the constructor, it must make sure |
| to invoke the base class constructor (\code{Thread.__init__()}) |
| before doing anything else to the thread. |
| \end{classdesc} |
| |
| \begin{methoddesc}{start}{} |
| Start the thread's activity. |
| |
| This must be called at most once per thread object. It |
| arranges for the object's \method{run()} method to be invoked in a |
| separate thread of control. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{run}{} |
| Method representing the thread's activity. |
| |
| You may override this method in a subclass. The standard |
| \method{run()} method invokes the callable object passed to the object's constructor as the |
| \var{target} argument, if any, with sequential and keyword |
| arguments taken from the \var{args} and \var{kwargs} arguments, |
| respectively. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{join}{\optional{timeout}} |
| Wait until the thread terminates. |
| This blocks the calling thread until the thread whose \method{join()} |
| method is called terminates -- either normally or through an |
| unhandled exception -- or until the optional timeout occurs. |
| |
| When the \var{timeout} argument is present and not \code{None}, it should |
| be a floating point number specifying a timeout for the |
| operation in seconds (or fractions thereof). |
| |
| A thread can be \method{join()}ed many times. |
| |
| A thread cannot join itself because this would cause a |
| deadlock. |
| |
| It is an error to attempt to \method{join()} a thread before it has |
| been started. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{getName}{} |
| Return the thread's name. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{setName}{name} |
| Set the thread's name. |
| |
| The name is a string used for identification purposes only. |
| It has no semantics. Multiple threads may be given the same |
| name. The initial name is set by the constructor. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isAlive}{} |
| Return whether the thread is alive. |
| |
| Roughly, a thread is alive from the moment the \method{start()} method |
| returns until its \method{run()} method terminates. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{isDaemon}{} |
| Return the thread's daemon flag. |
| \end{methoddesc} |
| |
| \begin{methoddesc}{setDaemon}{daemonic} |
| Set the thread's daemon flag to the Boolean value \var{daemonic}. |
| This must be called before \method{start()} is called. |
| |
| The initial value is inherited from the creating thread. |
| |
| The entire Python program exits when no active non-daemon |
| threads are left. |
| \end{methoddesc} |