Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 73d01e2

Browse files
mattwang44mattwang44
committed
Deploying to gh-pages from @ 7cf33e8 🚀
1 parent 92b4d80 commit 73d01e2

File tree

535 files changed

+8398
-8207
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

535 files changed

+8398
-8207
lines changed

‎.buildinfo

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: ed20a0ffdb2c79674424722536501fd3
3+
config: de39b7ffcd4cf530c39bb29a68f8fdc6
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_sources/c-api/init.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1218,7 +1218,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
12181218
.. c:function:: void PyThreadState_DeleteCurrent(void)
12191219
12201220
Destroy the current thread state and release the global interpreter lock.
1221-
Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
1221+
Like :c:func:`PyThreadState_Delete`, the global interpreter lock must
12221222
be held. The thread state must have been reset with a previous call
12231223
to :c:func:`PyThreadState_Clear`.
12241224

‎_sources/howto/free-threading-python.rst.txt

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
.. _freethreading-python-howto:
2+
3+
**********************************************
4+
Python experimental support for free threading
5+
**********************************************
6+
7+
Starting with the 3.13 release, CPython has experimental support for a build of
8+
Python called :term:`free threading` where the :term:`global interpreter lock`
9+
(GIL) is disabled. Free-threaded execution allows for full utilization of the
10+
available processing power by running threads in parallel on available CPU cores.
11+
While not all software will benefit from this automatically, programs
12+
designed with threading in mind will run faster on multi-core hardware.
13+
14+
**The free-threaded mode is experimental** and work is ongoing to improve it:
15+
expect some bugs and a substantial single-threaded performance hit.
16+
17+
This document describes the implications of free threading
18+
for Python code. See :ref:`freethreading-extensions-howto` for information on
19+
how to write C extensions that support the free-threaded build.
20+
21+
.. seealso::
22+
23+
:pep:`703` – Making the Global Interpreter Lock Optional in CPython for an
24+
overall description of free-threaded Python.
25+
26+
27+
Installation
28+
============
29+
30+
Starting with Python 3.13, the official macOS and Windows installers
31+
optionally support installing free-threaded Python binaries. The installers
32+
are available at https://www.python.org/downloads/.
33+
34+
For information on other platforms, see the `Installing a Free-Threaded Python
35+
<https://py-free-threading.github.io/installing_cpython/>`_, a
36+
community-maintained installation guide for installing free-threaded Python.
37+
38+
When building CPython from source, the :option:`--disable-gil` configure option
39+
should be used to build a free-threaded Python interpreter.
40+
41+
42+
Identifying free-threaded Python
43+
================================
44+
45+
To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
46+
and :attr:`sys.version` contain "experimental free-threading build".
47+
The new :func:`sys._is_gil_enabled` function can be used to check whether
48+
the GIL is actually disabled in the running process.
49+
50+
The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can
51+
be used to determine whether the build supports free threading. If the variable
52+
is set to ``1``, then the build supports free threading. This is the recommended
53+
mechanism for decisions related to the build configuration.
54+
55+
56+
The global interpreter lock in free-threaded Python
57+
===================================================
58+
59+
Free-threaded builds of CPython support optionally running with the GIL enabled
60+
at runtime using the environment variable :envvar:`PYTHON_GIL` or
61+
the command-line option :option:`-X gil`.
62+
63+
The GIL may also automatically be enabled when importing a C-API extension
64+
module that is not explicitly marked as supporting free threading. A warning
65+
will be printed in this case.
66+
67+
In addition to individual package documentation, the following websites track
68+
the status of popular packages support for free threading:
69+
70+
* https://py-free-threading.github.io/tracking/
71+
* https://hugovk.github.io/free-threaded-wheels/
72+
73+
74+
Thread safety
75+
=============
76+
77+
The free-threaded build of CPython aims to provide similar thread-safety
78+
behavior at the Python level to the default GIL-enabled build. Built-in
79+
types like :class:`dict`, :class:`list`, and :class:`set` use internal locks
80+
to protect against concurrent modifications in ways that behave similarly to
81+
the GIL. However, Python has not historically guaranteed specific behavior for
82+
concurrent modifications to these built-in types, so this should be treated
83+
as a description of the current implementation, not a guarantee of current or
84+
future behavior.
85+
86+
.. note::
87+
88+
It's recommended to use the :class:`threading.Lock` or other synchronization
89+
primitives instead of relying on the internal locks of built-in types, when
90+
possible.
91+
92+
93+
Known limitations
94+
=================
95+
96+
This section describes known limitations of the free-threaded CPython build.
97+
98+
Immortalization
99+
---------------
100+
101+
The free-threaded build of the 3.13 release makes some objects :term:`immortal`.
102+
Immortal objects are not deallocated and have reference counts that are
103+
never modified. This is done to avoid reference count contention that would
104+
prevent efficient multi-threaded scaling.
105+
106+
An object will be made immortal when a new thread is started for the first time
107+
after the main thread is running. The following objects are immortalized:
108+
109+
* :ref:`function <user-defined-funcs>` objects declared at the module level
110+
* :ref:`method <instance-methods>` descriptors
111+
* :ref:`code <code-objects>` objects
112+
* :term:`module` objects and their dictionaries
113+
* :ref:`classes <classes>` (type objects)
114+
115+
Because immortal objects are never deallocated, applications that create many
116+
objects of these types may see increased memory usage. This is expected to be
117+
addressed in the 3.14 release.
118+
119+
Additionally, numeric and string literals in the code as well as strings
120+
returned by :func:`sys.intern` are also immortalized. This behavior is
121+
expected to remain in the 3.14 free-threaded build.
122+
123+
124+
Frame objects
125+
-------------
126+
127+
It is not safe to access :ref:`frame <frame-objects>` objects from other
128+
threads and doing so may cause your program to crash . This means that
129+
:func:`sys._current_frames` is generally not safe to use in a free-threaded
130+
build. Functions like :func:`inspect.currentframe` and :func:`sys._getframe`
131+
are generally safe as long as the resulting frame object is not passed to
132+
another thread.
133+
134+
Iterators
135+
---------
136+
137+
Sharing the same iterator object between multiple threads is generally not
138+
safe and threads may see duplicate or missing elements when iterating or crash
139+
the interpreter.
140+
141+
142+
Single-threaded performance
143+
---------------------------
144+
145+
The free-threaded build has additional overhead when executing Python code
146+
compared to the default GIL-enabled build. In 3.13, this overhead is about
147+
40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
148+
Programs that spend most of their time in C extensions or I/O will see
149+
less of an impact. The largest impact is because the specializing adaptive
150+
interpreter (:pep:`659`) is disabled in the free-threaded build. We expect
151+
to re-enable it in a thread-safe way in the 3.14 release. This overhead is
152+
expected to be reduced in upcoming Python release. We are aiming for an
153+
overhead of 10% or less on the pyperformance suite compared to the default
154+
GIL-enabled build.

‎_sources/howto/index.rst.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Python Library Reference.
3232
isolating-extensions.rst
3333
timerfd.rst
3434
mro.rst
35+
free-threading-python.rst
3536
free-threading-extensions.rst
3637

3738
General:
@@ -52,6 +53,7 @@ General:
5253
Advanced development:
5354

5455
* :ref:`curses-howto`
56+
* :ref:`freethreading-python-howto`
5557
* :ref:`freethreading-extensions-howto`
5658
* :ref:`isolating-extensions-howto`
5759
* :ref:`python_2.3_mro`

‎_sources/library/datetime.rst.txt

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,20 @@ Instance attributes (read-only):
295295

296296
Between 0 and 86,399 inclusive.
297297

298+
.. caution::
299+
300+
It is a somewhat common bug for code to unintentionally use this attribute
301+
when it is actually intended to get a :meth:`~timedelta.total_seconds`
302+
value instead:
303+
304+
.. doctest::
305+
306+
>>> from datetime import timedelta
307+
>>> duration = timedelta(seconds=11235813)
308+
>>> duration.days, duration.seconds
309+
(130, 3813)
310+
>>> duration.total_seconds()
311+
11235813.0
298312

299313
.. attribute:: timedelta.microseconds
300314

@@ -351,7 +365,7 @@ Supported operations:
351365
| | same value. (2) |
352366
+--------------------------------+-----------------------------------------------+
353367
| ``-t1`` | Equivalent to ``timedelta(-t1.days, |
354-
| | -t1.seconds*, -t1.microseconds)``, |
368+
| | -t1.seconds, -t1.microseconds)``, |
355369
| | and to ``t1 * -1``. (1)(4) |
356370
+--------------------------------+-----------------------------------------------+
357371
| ``abs(t)`` | Equivalent to ``+t`` when ``t.days >= 0``, |

‎_sources/library/gc.rst.txt

Lines changed: 14 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -40,18 +40,11 @@ The :mod:`gc` module provides the following functions:
4040

4141
.. function:: collect(generation=2)
4242

43-
Perform a collection. The optional argument *generation*
43+
With no arguments, run a full collection. The optional argument *generation*
4444
may be an integer specifying which generation to collect (from 0 to 2). A
4545
:exc:`ValueError` is raised if the generation number is invalid. The sum of
4646
collected objects and uncollectable objects is returned.
4747

48-
Calling ``gc.collect(0)`` will perform a GC collection on the young generation.
49-
50-
Calling ``gc.collect(1)`` will perform a GC collection on the young generation
51-
and an increment of the old generation.
52-
53-
Calling ``gc.collect(2)`` or ``gc.collect()`` performs a full collection
54-
5548
The free lists maintained for a number of built-in types are cleared
5649
whenever a full collection or collection of the highest generation (2)
5750
is run. Not all items in some free lists may be freed due to the
@@ -60,9 +53,6 @@ The :mod:`gc` module provides the following functions:
6053
The effect of calling ``gc.collect()`` while the interpreter is already
6154
performing a collection is undefined.
6255

63-
.. versionchanged:: 3.13
64-
``generation=1`` performs an increment of collection.
65-
6656

6757
.. function:: set_debug(flags)
6858

@@ -78,20 +68,13 @@ The :mod:`gc` module provides the following functions:
7868

7969
.. function:: get_objects(generation=None)
8070

81-
8271
Returns a list of all objects tracked by the collector, excluding the list
83-
returned. If *generation* is not ``None``, return only the objects as follows:
84-
85-
* 0: All objects in the young generation
86-
* 1: No objects, as there is no generation 1 (as of Python 3.13)
87-
* 2: All objects in the old generation
72+
returned. If *generation* is not ``None``, return only the objects tracked by
73+
the collector that are in that generation.
8874

8975
.. versionchanged:: 3.8
9076
New *generation* parameter.
9177

92-
.. versionchanged:: 3.13
93-
Generation 1 is removed
94-
9578
.. audit-event:: gc.get_objects generation gc.get_objects
9679

9780
.. function:: get_stats()
@@ -118,27 +101,19 @@ The :mod:`gc` module provides the following functions:
118101
Set the garbage collection thresholds (the collection frequency). Setting
119102
*threshold0* to zero disables collection.
120103

121-
The GC classifies objects into two generations depending on whether they have
122-
survived a collection. New objects are placed in the young generation. If an
123-
object survives a collection it is moved into the old generation.
124-
125-
In order to decide when to run, the collector keeps track of the number of object
104+
The GC classifies objects into three generations depending on how many
105+
collection sweeps they have survived. New objects are placed in the youngest
106+
generation (generation ``0``). If an object survives a collection it is moved
107+
into the next older generation. Since generation ``2`` is the oldest
108+
generation, objects in that generation remain there after a collection. In
109+
order to decide when to run, the collector keeps track of the number object
126110
allocations and deallocations since the last collection. When the number of
127111
allocations minus the number of deallocations exceeds *threshold0*, collection
128-
starts. For each collection, all the objects in the young generation and some
129-
fraction of the old generation is collected.
130-
131-
The fraction of the old generation that is collected is **inversely** proportional
132-
to *threshold1*. The larger *threshold1* is, the slower objects in the old generation
133-
are collected.
134-
For the default value of 10, 1% of the old generation is scanned during each collection.
135-
136-
*threshold2* is ignored.
137-
138-
See `Garbage collector design <https://devguide.python.org/garbage_collector>`_ for more information.
139-
140-
.. versionchanged:: 3.13
141-
*threshold2* is ignored
112+
starts. Initially only generation ``0`` is examined. If generation ``0`` has
113+
been examined more than *threshold1* times since generation ``1`` has been
114+
examined, then generation ``1`` is examined as well.
115+
With the third generation, things are a bit more complicated,
116+
see `Collecting the oldest generation <https://devguide.python.org/garbage_collector/#collecting-the-oldest-generation>`_ for more information.
142117

143118

144119
.. function:: get_count()

‎_sources/reference/datamodel.rst.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -831,6 +831,7 @@ this case, the special read-only attribute :attr:`!__self__` is set to the objec
831831
denoted by *alist*. (The attribute has the same semantics as it does with
832832
:attr:`other instance methods <method.__self__>`.)
833833

834+
.. _classes:
834835

835836
Classes
836837
^^^^^^^

0 commit comments

Comments
 (0)