Lines Matching +full:hook +full:- +full:run +full:- +full:in +full:- +full:context
1 :mod:`threading` --- Thread-based parallelism
5 :synopsis: Thread-based parallelism.
9 --------------
11 This module constructs higher-level threading interfaces on top of the lower
20 methods and functions in this module in the Python 2.x series are still
43 Handle uncaught exception raised by :func:`Thread.run`.
59 exceptions raised by :func:`Thread.run` are handled.
61 Storing *exc_value* using a custom hook can create a reference cycle. It
65 Storing *thread* using a custom hook can resurrect it if it is set to an
67 hook completes to avoid resurrecting objects.
79 to be used e.g. to index a dictionary of thread-specific data. Thread
89 This is a non-negative integer.
90 Its value may be used to uniquely identify this particular thread system-wide
108 Return the main :class:`Thread` object. In normal conditions, the
121 :meth:`~Thread.run` method is called.
130 :meth:`~Thread.run` method is called.
145 minimum stack size > 32 KiB or requiring allocation in multiples of the system
146 memory page size - platform documentation should be referred to for more
148 the suggested approach in the absence of more specific information).
165 This module defines a number of classes, which are detailed in the sections
170 they are separate objects in Python. Python's :class:`Thread` class supports a
174 when implemented, are mapped to module-level functions.
179 Thread-Local Data
180 -----------------
182 Thread-local data is data whose values are thread specific. To manage
183 thread-local data, just create an instance of :class:`local` (or a
194 A class that represents thread-local data.
200 .. _thread-objects:
203 --------------
205 The :class:`Thread` class represents an activity that is run in a separate
207 callable object to the constructor, or by overriding the :meth:`~Thread.run`
208 method in a subclass. No other methods (except for the constructor) should be
209 overridden in a subclass. In other words, *only* override the
210 :meth:`~Thread.__init__` and :meth:`~Thread.run` methods of this class.
213 thread's :meth:`~Thread.start` method. This invokes the :meth:`~Thread.run`
214 method in a separate thread of control.
217 stops being alive when its :meth:`~Thread.run` method terminates -- either
228 If the :meth:`~Thread.run` method raises an exception,
241 If you want your threads to stop gracefully, make them non-daemonic and
245 control in the Python program. It is not a daemon thread.
264 *target* is the callable object to be invoked by the :meth:`run` method.
268 form "Thread-*N*" where *N* is a small decimal number.
291 object's :meth:`~Thread.run` method to be invoked in a separate thread
297 .. method:: run()
301 You may override this method in a subclass. The standard :meth:`run`
309 the thread whose :meth:`~Thread.join` method is called terminates -- either
310 normally or through an unhandled exception -- or until the optional
314 floating point number specifying a timeout for the operation in seconds
317 decide whether a timeout happened -- if the thread is still alive, the
353 This is a non-negative integer, or ``None`` if the thread has not
357 this particular thread system-wide (until the thread terminates,
363 system-wide) from the time the thread is created until the thread
374 This method returns ``True`` just before the :meth:`~Thread.run` method
375 starts until just after the :meth:`~Thread.run` method terminates. The
384 therefore all threads created in the main thread default to
387 The entire Python program exits when no alive non-daemon threads are left.
396 .. impl-detail::
398 In CPython, due to the :term:`Global Interpreter Lock`, only one thread
399 can execute Python code at once (even though certain performance-oriented
402 resources of multi-core machines, you are advised to use
404 However, threading is still an appropriate model if you want to run
405 multiple I/O-bound tasks simultaneously.
408 .. _lock-objects:
411 ------------
414 particular thread when locked. In Python, it is currently the lowest level
418 A primitive lock is in one of two states, "locked" or "unlocked". It is created
419 in the unlocked state. It has two basic methods, :meth:`~Lock.acquire` and
422 :meth:`~Lock.acquire` blocks until a call to :meth:`~Lock.release` in another
425 called in the locked state; it changes the state to unlocked and returns
429 Locks also support the :ref:`context management protocol <with-locks>`.
431 When more than one thread is blocked in :meth:`~Lock.acquire` waiting for the
450 .. method:: acquire(blocking=True, timeout=-1)
452 Acquire a lock, blocking or non-blocking.
461 When invoked with the floating-point *timeout* argument set to a positive
463 and as long as the lock cannot be acquired. A *timeout* argument of ``-1``
497 .. _rlock-objects:
500 -------------
504 and "recursion level" in addition to the locked/unlocked state used by primitive
505 locks. In the locked state, some thread owns the lock; in the unlocked state,
513 allows another thread blocked in :meth:`~Lock.acquire` to proceed.
515 Reentrant locks also support the :ref:`context management protocol <with-locks>`.
530 .. method:: acquire(blocking=True, timeout=-1)
532 Acquire a lock, blocking or non-blocking.
540 There is no return value in this case.
549 When invoked with the floating-point *timeout* argument set to a positive
573 .. _condition-objects:
576 -----------------
579 passed in or one will be created by default. Passing one in is useful when
583 A condition variable obeys the :ref:`context management protocol <with-locks>`:
593 re-acquires the lock and returns. It is also possible to specify a timeout.
606 synchronize access to some shared state; threads that are interested in a
610 the state in such a way that it could possibly be a desired state for one
612 producer-consumer situation with unlimited buffer capacity::
628 no longer hold true. This is inherent to multi-threaded programming. The
639 waiting threads. E.g. in a typical producer-consumer situation, adding one
673 condition variable in another thread, or until the optional timeout
674 occurs. Once awakened or timed out, it re-acquires the lock and returns.
677 floating point number specifying a timeout for the operation in seconds
688 The return value is ``True`` unless a given *timeout* expired, in which
712 held when called and is re-acquired on return. The predicate is evaluated
724 variable; it is a no-op if no threads are waiting.
743 .. _semaphore-objects:
746 -----------------
748 This is one of the oldest synchronization primitives in the history of computer
759 Semaphores also support the :ref:`context management protocol <with-locks>`.
789 order in which threads are awoken should not be relied on.
796 most *timeout* seconds. If acquire does not complete successfully in
813 :exc:`ValueError` is raised. In most situations semaphores are used to guard
821 .. _semaphore-examples:
827 a database server. In any situation where the size of the resource is fixed,
849 .. _event-objects:
852 -------------
895 floating point number specifying a timeout for the operation in seconds
907 .. _timer-objects:
910 -------------
912 This class represents an action that should be run only after a certain amount
913 of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread`
933 Create a timer that will run *function* with arguments *args* and keyword
944 only work if the timer is still in its waiting stage.
948 ---------------
989 provided, it is used in preference to any that was supplied to the class
992 The return value is an integer in the range 0 to *parties* -- 1, different
1036 The number of threads currently waiting in the barrier.
1040 A boolean that is ``True`` if the barrier is in the broken state.
1049 .. _with-locks:
1051 Using locks, conditions, and semaphores in the :keyword:`!with` statement
1052 -------------------------------------------------------------------------
1055 :meth:`release` methods can be used as context managers for a :keyword:`with`
1073 :keyword:`with` statement context managers.