Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit0007c9b

Browse files
miss-islingtondonBarbosZeroIntensity
authored
[3.13]gh-124210: Add introduction tothreading docs (GH-127046) (#134091)
Co-authored-by: Semyon Moroz <donbarbos@proton.me>Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
1 parentbc1a6ec commit0007c9b

File tree

1 file changed

+89
-25
lines changed

1 file changed

+89
-25
lines changed

‎Doc/library/threading.rst

Lines changed: 89 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,52 @@
1111
This module constructs higher-level threading interfaces on top of the lower
1212
level:mod:`_thread` module.
1313

14+
..include::../includes/wasm-notavail.rst
15+
16+
Introduction
17+
------------
18+
19+
The:mod:`!threading` module provides a way to run multiple `threads
20+
<https://en.wikipedia.org/wiki/Thread_(computing)>`_ (smaller
21+
units of a process) concurrently within a single process. It allows for the
22+
creation and management of threads, making it possible to execute tasks in
23+
parallel, sharing memory space. Threads are particularly useful when tasks are
24+
I/O bound, such as file operations or making network requests,
25+
where much of the time is spent waiting for external resources.
26+
27+
A typical use case for:mod:`!threading` includes managing a pool of worker
28+
threads that can process multiple tasks concurrently. Here's a basic example of
29+
creating and starting threads using:class:`~threading.Thread`::
30+
31+
import threading
32+
import time
33+
34+
def crawl(link, delay=3):
35+
print(f"crawl started for {link}")
36+
time.sleep(delay) # Blocking I/O (simulating a network request)
37+
print(f"crawl ended for {link}")
38+
39+
links = [
40+
"https://python.org",
41+
"https://docs.python.org",
42+
"https://peps.python.org",
43+
]
44+
45+
# Start threads for each link
46+
threads = []
47+
for link in links:
48+
# Using `args` to pass positional arguments and `kwargs` for keyword arguments
49+
t = threading.Thread(target=crawl, args=(link,), kwargs={"delay": 2})
50+
threads.append(t)
51+
52+
# Start each thread
53+
for t in threads:
54+
t.start()
55+
56+
# Wait for all threads to finish
57+
for t in threads:
58+
t.join()
59+
1460
..versionchanged::3.7
1561
This module used to be optional, it is now always available.
1662

@@ -45,7 +91,25 @@ level :mod:`_thread` module.
4591
However, threading is still an appropriate model if you want to run
4692
multiple I/O-bound tasks simultaneously.
4793

48-
..include::../includes/wasm-notavail.rst
94+
GIL and performance considerations
95+
----------------------------------
96+
97+
Unlike the:mod:`multiprocessing` module, which uses separate processes to
98+
bypass the:term:`global interpreter lock` (GIL), the threading module operates
99+
within a single process, meaning that all threads share the same memory space.
100+
However, the GIL limits the performance gains of threading when it comes to
101+
CPU-bound tasks, as only one thread can execute Python bytecode at a time.
102+
Despite this, threads remain a useful tool for achieving concurrency in many
103+
scenarios.
104+
105+
As of Python 3.13, experimental:term:`free-threaded <free threading>` builds
106+
can disable the GIL, enabling true parallel execution of threads, but this
107+
feature is not available by default (see:pep:`703`).
108+
109+
.. TODO: At some point this feature will become available by default.
110+
111+
Reference
112+
---------
49113

50114
This module defines the following functions:
51115

@@ -62,7 +126,7 @@ This module defines the following functions:
62126

63127
Return the current:class:`Thread` object, corresponding to the caller's thread
64128
of control. If the caller's thread of control was not created through the
65-
:mod:`threading` module, a dummy thread object with limited functionality is
129+
:mod:`!threading` module, a dummy thread object with limited functionality is
66130
returned.
67131

68132
The function ``currentThread`` is a deprecated alias for this function.
@@ -157,13 +221,13 @@ This module defines the following functions:
157221

158222
..index::single: trace function
159223

160-
Set a trace function for all threads started from the:mod:`threading` module.
224+
Set a trace function for all threads started from the:mod:`!threading` module.
161225
The *func* will be passed to:func:`sys.settrace` for each thread, before its
162226
:meth:`~Thread.run` method is called.
163227

164228
..function::settrace_all_threads(func)
165229

166-
Set a trace function for all threads started from the:mod:`threading` module
230+
Set a trace function for all threads started from the:mod:`!threading` module
167231
and all Python threads that are currently executing.
168232

169233
The *func* will be passed to:func:`sys.settrace` for each thread, before its
@@ -186,13 +250,13 @@ This module defines the following functions:
186250

187251
..index::single: profile function
188252

189-
Set a profile function for all threads started from the:mod:`threading` module.
253+
Set a profile function for all threads started from the:mod:`!threading` module.
190254
The *func* will be passed to:func:`sys.setprofile` for each thread, before its
191255
:meth:`~Thread.run` method is called.
192256

193257
..function::setprofile_all_threads(func)
194258

195-
Set a profile function for all threads started from the:mod:`threading` module
259+
Set a profile function for all threads started from the:mod:`!threading` module
196260
and all Python threads that are currently executing.
197261

198262
The *func* will be passed to:func:`sys.setprofile` for each thread, before its
@@ -257,8 +321,8 @@ when implemented, are mapped to module-level functions.
257321
All of the methods described below are executed atomically.
258322

259323

260-
Thread-Local Data
261-
-----------------
324+
Thread-local data
325+
^^^^^^^^^^^^^^^^^
262326

263327
Thread-local data is data whose values are thread specific. If you
264328
have data that you want to be local to a thread, create a
@@ -389,8 +453,8 @@ affects what we see::
389453

390454
.. _thread-objects:
391455

392-
ThreadObjects
393-
--------------
456+
Threadobjects
457+
^^^^^^^^^^^^^^
394458

395459
The:class:`Thread` class represents an activity that is run in a separate
396460
thread of control. There are two ways to specify the activity: by passing a
@@ -608,8 +672,8 @@ since it is impossible to detect the termination of alien threads.
608672

609673
.. _lock-objects:
610674

611-
LockObjects
612-
------------
675+
Lockobjects
676+
^^^^^^^^^^^^
613677

614678
A primitive lock is a synchronization primitive that is not owned by a
615679
particular thread when locked. In Python, it is currently the lowest level
@@ -698,8 +762,8 @@ All methods are executed atomically.
698762

699763
.. _rlock-objects:
700764

701-
RLockObjects
702-
-------------
765+
RLockobjects
766+
^^^^^^^^^^^^^
703767

704768
A reentrant lock is a synchronization primitive that may be acquired multiple
705769
times by the same thread. Internally, it uses the concepts of "owning thread"
@@ -801,8 +865,8 @@ call release as many times the lock has been acquired can lead to deadlock.
801865

802866
.. _condition-objects:
803867

804-
ConditionObjects
805-
-----------------
868+
Conditionobjects
869+
^^^^^^^^^^^^^^^^^
806870

807871
A condition variable is always associated with some kind of lock; this can be
808872
passed in or one will be created by default. Passing one in is useful when
@@ -973,8 +1037,8 @@ item to the buffer only needs to wake up one consumer thread.
9731037

9741038
.. _semaphore-objects:
9751039

976-
SemaphoreObjects
977-
-----------------
1040+
Semaphoreobjects
1041+
^^^^^^^^^^^^^^^^^
9781042

9791043
This is one of the oldest synchronization primitives in the history of computer
9801044
science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
@@ -1054,7 +1118,7 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
10541118

10551119
.. _semaphore-examples:
10561120

1057-
:class:`Semaphore`Example
1121+
:class:`Semaphore`example
10581122
^^^^^^^^^^^^^^^^^^^^^^^^^^
10591123

10601124
Semaphores are often used to guard resources with limited capacity, for example,
@@ -1082,8 +1146,8 @@ causes the semaphore to be released more than it's acquired will go undetected.
10821146

10831147
.. _event-objects:
10841148

1085-
EventObjects
1086-
-------------
1149+
Eventobjects
1150+
^^^^^^^^^^^^^
10871151

10881152
This is one of the simplest mechanisms for communication between threads: one
10891153
thread signals an event and other threads wait for it.
@@ -1139,8 +1203,8 @@ method. The :meth:`~Event.wait` method blocks until the flag is true.
11391203

11401204
.. _timer-objects:
11411205

1142-
TimerObjects
1143-
-------------
1206+
Timerobjects
1207+
^^^^^^^^^^^^^
11441208

11451209
This class represents an action that should be run only after a certain amount
11461210
of time has passed --- a timer.:class:`Timer` is a subclass of:class:`Thread`
@@ -1177,8 +1241,8 @@ For example::
11771241
only work if the timer is still in its waiting stage.
11781242

11791243

1180-
BarrierObjects
1181-
---------------
1244+
Barrierobjects
1245+
^^^^^^^^^^^^^^^
11821246

11831247
..versionadded::3.2
11841248

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp