Changeset 391 for python/trunk/Doc/library/threading.rst
- Timestamp:
- Mar 19, 2014, 11:31:01 PM (11 years ago)
- Location:
- python/trunk
- Files:
-
- 2 edited
-
. (modified) (1 prop)
-
Doc/library/threading.rst (modified) (29 diffs)
Legend:
- Unmodified
- Added
- Removed
-
python/trunk
-
Property svn:mergeinfo
set to
/python/vendor/Python-2.7.6 merged eligible /python/vendor/current merged eligible
-
Property svn:mergeinfo
set to
-
python/trunk/Doc/library/threading.rst
r2 r391 5 5 :synopsis: Higher-level threading interface. 6 6 7 **Source code:** :source:`Lib/threading.py` 8 9 -------------- 7 10 8 11 This module constructs higher-level threading interfaces on top of the lower … … 15 18 .. note:: 16 19 17 Starting with Python 2.6, this module provides PEP 8compliant aliases and20 Starting with Python 2.6, this module provides :pep:`8` compliant aliases and 18 21 properties to replace the ``camelCase`` names that were inspired by Java's 19 22 threading API. This updated API is compatible with that of the … … 27 30 instead of :exc:`AssertionError` if called erroneously. 28 31 32 .. impl-detail:: 33 34 In CPython, due to the :term:`Global Interpreter Lock`, only one thread 35 can execute Python code at once (even though certain performance-oriented 36 libraries might overcome this limitation). 37 If you want your application to make better use of the computational 38 resources of multi-core machines, you are advised to use 39 :mod:`multiprocessing`. However, threading is still an appropriate model 40 if you want to run multiple I/O-bound tasks simultaneously. 41 29 42 30 43 This module defines the following functions and objects: … … 35 48 Return the number of :class:`Thread` objects currently alive. The returned 36 49 count is equal to the length of the list returned by :func:`.enumerate`. 50 51 .. versionchanged:: 2.6 52 Added ``active_count()`` spelling. 37 53 38 54 … … 43 59 variable allows one or more threads to wait until they are notified by another 44 60 thread. 61 62 See :ref:`condition-objects`. 45 63 46 64 … … 53 71 returned. 54 72 73 .. versionchanged:: 2.6 74 Added ``current_thread()`` spelling. 75 55 76 56 77 .. function:: enumerate() … … 70 91 is true. 71 92 93 See :ref:`event-objects`. 94 72 95 73 96 .. class:: local … … 93 116 acquired it, subsequent attempts to acquire it block, until it is released; any 94 117 thread may release it. 118 119 See :ref:`lock-objects`. 95 120 96 121 … … 101 126 reentrant lock, the same thread may acquire it again without blocking; the 102 127 thread must release it once for each time it has acquired it. 128 129 See :ref:`rlock-objects`. 103 130 104 131 … … 112 139 given, *value* defaults to 1. 113 140 141 See :ref:`semaphore-objects`. 142 114 143 115 144 .. function:: BoundedSemaphore([value]) … … 123 152 124 153 .. class:: Thread 154 :noindex: 125 155 126 156 A class that represents a thread of control. This class can be safely 127 157 subclassed in a limited fashion. 128 158 159 See :ref:`thread-objects`. 160 129 161 130 162 .. class:: Timer 163 :noindex: 131 164 132 165 A thread that executes a function after a specified interval has passed. 166 167 See :ref:`timer-objects`. 133 168 134 169 … … 139 174 Set a trace function for all threads started from the :mod:`threading` module. 140 175 The *func* will be passed to :func:`sys.settrace` for each thread, before its 141 :meth:` run` method is called.176 :meth:`~Thread.run` method is called. 142 177 143 178 .. versionadded:: 2.3 … … 150 185 Set a profile function for all threads started from the :mod:`threading` module. 151 186 The *func* will be passed to :func:`sys.setprofile` for each thread, before its 152 :meth:` run` method is called.187 :meth:`~Thread.run` method is called. 153 188 154 189 .. versionadded:: 2.3 … … 174 209 .. versionadded:: 2.5 175 210 211 212 .. exception:: ThreadError 213 214 Raised for various threading-related errors as described below. Note that 215 many interfaces use :exc:`RuntimeError` instead of :exc:`ThreadError`. 216 217 176 218 Detailed interfaces for the objects are documented below. 177 219 … … 219 261 through the :attr:`daemon` property. 220 262 263 .. note:: 264 Daemon threads are abruptly stopped at shutdown. Their resources (such 265 as open files, database transactions, etc.) may not be released properly. 266 If you want your threads to stop gracefully, make them non-daemonic and 267 use a suitable signalling mechanism such as an :class:`Event`. 268 221 269 There is a "main thread" object; this corresponds to the initial thread of 222 270 control in the Python program. It is not a daemon thread. … … 260 308 object's :meth:`run` method to be invoked in a separate thread of control. 261 309 262 This method will raise a :exc:`RuntimeE xception` if called more than once310 This method will raise a :exc:`RuntimeError` if called more than once 263 311 on the same thread object. 264 312 … … 294 342 raises the same exception. 295 343 296 .. method:: getName()297 setName()298 299 Old API for :attr:`~Thread.name`.300 301 344 .. attribute:: name 302 345 … … 304 347 Multiple threads may be given the same name. The initial name is set by 305 348 the constructor. 349 350 .. versionadded:: 2.6 351 352 .. method:: getName() 353 setName() 354 355 Pre-2.6 API for :attr:`~Thread.name`. 306 356 307 357 .. attribute:: ident … … 320 370 Return whether the thread is alive. 321 371 322 Roughly, a thread is alive from the moment the :meth:`start` method323 returns until its :meth:`run` method terminates.The module function372 This method returns ``True`` just before the :meth:`run` method starts 373 until just after the :meth:`run` method terminates. The module function 324 374 :func:`.enumerate` returns a list of all alive threads. 325 375 326 .. method:: isDaemon() 327 setDaemon() 328 329 Old API for :attr:`~Thread.daemon`. 376 .. versionchanged:: 2.6 377 Added ``is_alive()`` spelling. 330 378 331 379 .. attribute:: daemon … … 339 387 340 388 The entire Python program exits when no alive non-daemon threads are left. 389 390 .. versionadded:: 2.6 391 392 .. method:: isDaemon() 393 setDaemon() 394 395 Pre-2.6 API for :attr:`~Thread.daemon`. 341 396 342 397 … … 359 414 :meth:`release` method should only be called in the locked state; it changes the 360 415 state to unlocked and returns immediately. If an attempt is made to release an 361 unlocked lock, a :exc:` RuntimeError` will be raised.416 unlocked lock, a :exc:`ThreadError` will be raised. 362 417 363 418 When more than one thread is blocked in :meth:`acquire` waiting for the state to … … 369 424 370 425 371 .. method:: Lock.acquire([blocking =1])426 .. method:: Lock.acquire([blocking]) 372 427 373 428 Acquire a lock, blocking or non-blocking. 374 429 375 When invoked without arguments, block until the lock is unlocked, then set it to 376 locked, and return true. 377 378 When invoked with the *blocking* argument set to true, do the same thing as when 379 called without arguments, and return true. 380 381 When invoked with the *blocking* argument set to false, do not block. If a call 382 without an argument would block, return false immediately; otherwise, do the 383 same thing as when called without arguments, and return true. 430 When invoked with the *blocking* argument set to ``True`` (the default), 431 block until the lock is unlocked, then set it to locked and return ``True``. 432 433 When invoked with the *blocking* argument set to ``False``, do not block. 434 If a call with *blocking* set to ``True`` would block, return ``False`` 435 immediately; otherwise, set the lock to locked and return ``True``. 384 436 385 437 … … 392 444 to proceed. 393 445 394 Do not call this method when the lock is unlocked.446 When invoked on an unlocked lock, a :exc:`ThreadError` is raised. 395 447 396 448 There is no return value. … … 545 597 reacquired. 546 598 547 .. method:: notify( )548 549 Wake up a thread waiting on this condition, if any. If the calling thread550 has not acquired the lock when this method is called, a599 .. method:: notify(n=1) 600 601 By default, wake up one thread waiting on this condition, if any. If the 602 calling thread has not acquired the lock when this method is called, a 551 603 :exc:`RuntimeError` is raised. 552 604 553 This method wakes up one of the threads waiting for the condition 554 variable, if any are waiting; it is a no-op if no threads are waiting. 555 556 The current implementation wakes up exactly one thread, if any are 557 waiting. However, it's not safe to rely on this behavior. A future, 558 optimized implementation may occasionally wake up more than one thread. 559 560 Note: the awakened thread does not actually return from its :meth:`wait` 605 This method wakes up at most *n* of the threads waiting for the condition 606 variable; it is a no-op if no threads are waiting. 607 608 The current implementation wakes up exactly *n* threads, if at least *n* 609 threads are waiting. However, it's not safe to rely on this behavior. 610 A future, optimized implementation may occasionally wake up more than 611 *n* threads. 612 613 Note: an awakened thread does not actually return from its :meth:`wait` 561 614 call until it can reacquire the lock. Since :meth:`notify` does not 562 615 release the lock, its caller should. … … 569 622 calling thread has not acquired the lock when this method is called, a 570 623 :exc:`RuntimeError` is raised. 624 625 .. versionchanged:: 2.6 626 Added ``notify_all()`` spelling. 571 627 572 628 … … 625 681 626 682 Semaphores are often used to guard resources with limited capacity, for example, 627 a database server. In any situation where the size of the resource size is628 fixed, you should use a bounded semaphore. Before spawning any worker threads, 629 yourmain thread would initialize the semaphore::683 a database server. In any situation where the size of the resource is fixed, 684 you should use a bounded semaphore. Before spawning any worker threads, your 685 main thread would initialize the semaphore:: 630 686 631 687 maxconnections = 5 … … 668 724 Return true if and only if the internal flag is true. 669 725 726 .. versionchanged:: 2.6 727 Added ``is_set()`` spelling. 728 670 729 .. method:: set() 671 730 … … 707 766 and as such also functions as an example of creating custom threads. 708 767 709 Timers are started, as with threads, by calling their :meth:`start` method. The 710 timer can be stopped (before its action has begun) by calling the :meth:`cancel` 711 method. The interval the timer will wait before executing its action may not be 712 exactly the same as the interval specified by the user. 768 Timers are started, as with threads, by calling their :meth:`~Timer.start` 769 method. The timer can be stopped (before its action has begun) by calling the 770 :meth:`~Timer.cancel` method. The interval the timer will wait before 771 executing its action may not be exactly the same as the interval specified by 772 the user. 713 773 714 774 For example:: … … 759 819 -------------------------- 760 820 761 While the import machinery is thread safe, there are two key762 restrictions on threaded imports due to inherent limitations in the way 763 that thread safety isprovided:821 While the import machinery is thread-safe, there are two key restrictions on 822 threaded imports due to inherent limitations in the way that thread-safety is 823 provided: 764 824 765 825 * Firstly, other than in the main module, an import should not have the
Note:
See TracChangeset
for help on using the changeset viewer.
