Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(92868)

Unified Diff: Doc/library/threading.rst

Issue 10968: threading.Timer should be a class so that it can be derived
Patch Set: Created 8 years, 3 months ago
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « Doc/library/multiprocessing.rst ('k') | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -21,7 +21,7 @@ The :mod:`dummy_threading` module is pro
supported by this module.
-This module defines the following functions and objects:
+This module defines the following functions:
.. function:: active_count()
@@ -30,16 +30,6 @@ This module defines the following functi
count is equal to the length of the list returned by :func:`.enumerate`.
-.. function:: Condition()
- :noindex:
-
- 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.
-
- See :ref:`condition-objects`.
-
-
.. function:: current_thread()
Return the current :class:`Thread` object, corresponding to the caller's thread
@@ -67,89 +57,6 @@ This module defines the following functi
and threads that have not yet been started.
-.. function:: Event()
- :noindex:
-
- A factory function that returns a new event object. An event manages a flag
- that can be set to true with the :meth:`~Event.set` method and reset to false
- with the :meth:`clear` method. The :meth:`wait` method blocks until the flag
- is true.
-
- See :ref:`event-objects`.
-
-
-.. class:: local
-
- A class that represents thread-local data. Thread-local data are data whose
- values are thread specific. To manage thread-local data, just create an
- instance of :class:`local` (or a subclass) and store attributes on it::
-
- mydata = threading.local()
- mydata.x = 1
-
- The instance's values will be different for separate threads.
-
- For more details and extensive examples, see the documentation string of the
- :mod:`_threading_local` module.
-
-
-.. function:: 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.
-
- See :ref:`lock-objects`.
-
-
-.. function:: 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.
-
- See :ref:`rlock-objects`.
-
-
-.. function:: Semaphore(value=1)
- :noindex:
-
- A factory function that returns a new semaphore object. A semaphore manages a
- counter representing the number of :meth:`release` calls minus the number of
- :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method blocks
- if necessary until it can return without making the counter negative. If not
- given, *value* defaults to 1.
-
- See :ref:`semaphore-objects`.
-
-
-.. function:: BoundedSemaphore(value=1)
-
- A factory function that returns a new bounded semaphore object. A bounded
- semaphore checks to make sure its current value doesn't exceed its initial
- value. If it does, :exc:`ValueError` is raised. In most situations semaphores
- are used to guard resources with limited capacity. If the semaphore is released
- too many times it's a sign of a bug. If not given, *value* defaults to 1.
-
-
-.. class:: Thread
- :noindex:
-
- A class that represents a thread of control. This class can be safely
- subclassed in a limited fashion.
-
- See :ref:`thread-objects`.
-
-
-.. class:: Timer
- :noindex:
-
- A thread that executes a function after a specified interval has passed.
-
- See :ref:`timer-objects`.
-
-
.. function:: settrace(func)
.. index:: single: trace function
@@ -198,7 +105,23 @@ This module also defines the following c
.. versionadded:: 3.2
-Detailed interfaces for the objects are documented below.
+This module defines a number of classes. Most of them are documented in detail
+later in this document.
+
+.. class:: local
+
+ A class that represents thread-local data. Thread-local data are data whose
+ values are thread specific. To manage thread-local data, just create an
+ instance of :class:`local` (or a subclass) and store attributes on it::
+
+ mydata = threading.local()
+ mydata.x = 1
+
+ The instance's values will be different for separate threads.
+
+ For more details and extensive examples, see the documentation string of the
+ :mod:`_threading_local` module.
+
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,
@@ -216,7 +139,8 @@ All of the methods described below are e
Thread Objects
--------------
-This class represents an activity that is run in a separate thread of control.
+The :class:`Thread` 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 :meth:`run` method in a subclass. No other
methods (except for the constructor) should be overridden in a subclass. In
@@ -254,7 +178,7 @@ daemonic, and cannot be :meth:`join`\ ed
impossible to detect the termination of alien threads.
-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, \
verbose=None, *, daemon=None)
This constructor should always be called with keyword arguments. Arguments
@@ -287,6 +211,9 @@ impossible to detect the termination of
.. versionchanged:: 3.3
Added the *daemon* argument.
+ .. versionchanged:: 3.3
+ ``Thread`` used to be a factory function rather than the class itself.
ezio.melotti 2011/09/17 20:49:11 Something about this sentence sounds wrong to me.
+
.. method:: start()
Start the thread's activity.
@@ -414,6 +341,16 @@ and may vary across implementations.
All methods are executed atomically.
+.. class:: Lock()
+
+ The class implementing primitive lock objects. Once a thread has acquired a
+ lock, subsequent attempts to acquire it block, until it is released; any
+ thread may release it.
+
+ .. versionchanged:: 3.3
+ ``Lock`` used to be a factory function rather than the class itself.
+
+
.. method:: Lock.acquire(blocking=True, timeout=-1)
Acquire a lock, blocking or non-blocking.
@@ -476,6 +413,17 @@ pair) resets the lock to unlocked and al
:meth:`acquire` to proceed.
+.. class:: RLock()
+
+ This class implements reentrant lock objects. 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.
+
+ .. versionchanged:: 3.3
+ ``RLock`` used to be a factory function rather than the class itself.
+
+
.. method:: RLock.acquire(blocking=True, timeout=-1)
Acquire a lock, blocking or non-blocking.
@@ -584,10 +532,16 @@ the call as often as necessary.
.. class:: Condition(lock=None)
+ This class implements condition variable objects. A condition variable
+ allows one or more threads to wait until they are notified by another thread.
+
If the *lock* argument is given and not ``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.
+ .. versionchanged:: 3.3
+ ``Condition`` used to be a factory function rather than the class itself.
+
.. method:: acquire(*args)
Acquire the underlying lock. This method calls the corresponding method on
@@ -698,10 +652,19 @@ waiting until some other thread calls :m
.. class:: Semaphore(value=1)
+ This class implements semaphore objects. A semaphore manages a counter
+ representing the number of :meth:`release` calls minus the number of
+ :meth:`acquire` calls, plus an initial value. The :meth:`acquire` method
+ blocks if necessary until it can return without making the counter negative.
+ If not given, *value* defaults to 1.
+
The optional argument gives the initial *value* for the internal counter; it
defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
raised.
+ .. versionchanged:: 3.3
+ ``Semaphore`` used to be a factory function rather than the class itself.
+
.. method:: acquire(blocking=True, timeout=None)
Acquire a semaphore.
@@ -733,6 +696,19 @@ waiting until some other thread calls :m
than zero again, wake up that thread.
+.. class:: BoundedSemaphore(value=1)
+
+ Class implementing bounded semaphore objects. A bounded semaphore checks to
+ make sure its current value doesn't exceed its initial value. If it does,
+ :exc:`ValueError` is raised. In most situations semaphores are used to guard
+ resources with limited capacity. If the semaphore is released too many times
+ it's a sign of a bug. If not given, *value* defaults to 1.
+
+ .. versionchanged:: 3.3
+ ``BoundedSemaphore`` used to be a factory function rather than the class
+ itself.
+
+
.. _semaphore-examples:
:class:`Semaphore` Example
@@ -744,7 +720,7 @@ you should use a bounded semaphore. Bef
main thread would initialize the semaphore::
maxconnections = 5
- ...
+ # ...
pool_sema = BoundedSemaphore(value=maxconnections)
Once spawned, worker threads call the semaphore's acquire and release methods
@@ -752,7 +728,7 @@ when they need to connect to the server:
pool_sema.acquire()
conn = connectdb()
- ... use connection ...
+ # ... use connection ...
conn.close()
pool_sema.release()
@@ -775,7 +751,13 @@ An event object manages an internal flag
.. class:: Event()
- The internal flag is initially false.
+ Class implementing event objects. An event manages a flag that can be set to
+ true with the :meth:`~Event.set` method and reset to false with the
+ :meth:`clear` method. The :meth:`wait` method blocks until the flag is true.
+ The flag is initially false.
+
+ .. versionchanged:: 3.3
+ ``Event`` used to be a factory function rather than the class itself.
.. method:: is_set()
@@ -838,6 +820,9 @@ For example::
Create a timer that will run *function* with arguments *args* and keyword
arguments *kwargs*, after *interval* seconds have passed.
+ .. versionchanged:: 3.3
+ ``Timer`` used to be a factory function rather than the class itself.
+
.. method:: cancel()
Stop the timer, and cancel the execution of the timer's action. This will
« no previous file with comments | « Doc/library/multiprocessing.rst ('k') | no next file » | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+