2024-05-08 16:34:40 -03:00
|
|
|
:mod:`!_thread` --- Low-level threading API
|
|
|
|
===========================================
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2008-05-25 10:05:15 -03:00
|
|
|
.. module:: _thread
|
|
|
|
:synopsis: Low-level threading API.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. index::
|
|
|
|
single: light-weight processes
|
|
|
|
single: processes, light-weight
|
|
|
|
single: binary semaphores
|
|
|
|
single: semaphores, binary
|
|
|
|
|
2016-06-11 16:02:54 -03:00
|
|
|
--------------
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
This module provides low-level primitives for working with multiple threads
|
Merged revisions 57778-58052 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r57820 | georg.brandl | 2007-08-31 08:59:27 +0200 (Fri, 31 Aug 2007) | 2 lines
Document new shorthand notation for index entries.
........
r57827 | georg.brandl | 2007-08-31 10:47:51 +0200 (Fri, 31 Aug 2007) | 2 lines
Fix subitem markup.
........
r57833 | martin.v.loewis | 2007-08-31 12:01:07 +0200 (Fri, 31 Aug 2007) | 1 line
Mark registry components as 64-bit on Win64.
........
r57854 | bill.janssen | 2007-08-31 21:02:23 +0200 (Fri, 31 Aug 2007) | 1 line
deprecate use of FakeSocket
........
r57855 | bill.janssen | 2007-08-31 21:02:46 +0200 (Fri, 31 Aug 2007) | 1 line
remove mentions of socket.ssl in comments
........
r57856 | bill.janssen | 2007-08-31 21:03:31 +0200 (Fri, 31 Aug 2007) | 1 line
remove use of non-existent SSLFakeSocket in apparently untested code
........
r57859 | martin.v.loewis | 2007-09-01 08:36:03 +0200 (Sat, 01 Sep 2007) | 3 lines
Bug #1737210: Change Manufacturer of Windows installer to PSF.
Will backport to 2.5.
........
r57865 | georg.brandl | 2007-09-01 09:51:24 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix RST link (backport from Py3k).
........
r57876 | georg.brandl | 2007-09-01 17:49:49 +0200 (Sat, 01 Sep 2007) | 2 lines
Document sets' ">" and "<" operations (backport from py3k).
........
r57878 | skip.montanaro | 2007-09-01 19:40:03 +0200 (Sat, 01 Sep 2007) | 4 lines
Added a note and examples to explain that re.split does not split on an
empty pattern match. (issue 852532).
........
r57879 | walter.doerwald | 2007-09-01 20:18:09 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix wrong function names.
........
r57880 | walter.doerwald | 2007-09-01 20:34:05 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix typo.
........
r57889 | andrew.kuchling | 2007-09-01 22:31:59 +0200 (Sat, 01 Sep 2007) | 1 line
Markup fix
........
r57892 | andrew.kuchling | 2007-09-01 22:43:36 +0200 (Sat, 01 Sep 2007) | 1 line
Add various items
........
r57895 | andrew.kuchling | 2007-09-01 23:17:58 +0200 (Sat, 01 Sep 2007) | 1 line
Wording change
........
r57896 | andrew.kuchling | 2007-09-01 23:18:31 +0200 (Sat, 01 Sep 2007) | 1 line
Add more items
........
r57904 | ronald.oussoren | 2007-09-02 11:46:07 +0200 (Sun, 02 Sep 2007) | 3 lines
Macosx: this patch ensures that the value of MACOSX_DEPLOYMENT_TARGET used
by the Makefile is also used at configure-time.
........
r57925 | georg.brandl | 2007-09-03 09:16:46 +0200 (Mon, 03 Sep 2007) | 2 lines
Fix #883466: don't allow Unicode as arguments to quopri and uu codecs.
........
r57936 | matthias.klose | 2007-09-04 01:33:04 +0200 (Tue, 04 Sep 2007) | 2 lines
- Added support for linking the bsddb module against BerkeleyDB 4.6.x.
........
r57954 | mark.summerfield | 2007-09-04 10:16:15 +0200 (Tue, 04 Sep 2007) | 3 lines
Added cross-references plus a note about dict & list shallow copying.
........
r57958 | martin.v.loewis | 2007-09-04 11:51:57 +0200 (Tue, 04 Sep 2007) | 3 lines
Document that we rely on the OS to release the crypto
context. Fixes #1626801.
........
r57960 | martin.v.loewis | 2007-09-04 15:13:14 +0200 (Tue, 04 Sep 2007) | 3 lines
Patch #1388440: Add set_completion_display_matches_hook and
get_completion_type to readline.
........
r57961 | martin.v.loewis | 2007-09-04 16:19:28 +0200 (Tue, 04 Sep 2007) | 3 lines
Patch #1031213: Decode source line in SyntaxErrors back to its original
source encoding. Will backport to 2.5.
........
r57972 | matthias.klose | 2007-09-04 20:17:36 +0200 (Tue, 04 Sep 2007) | 3 lines
- Makefile.pre.in(buildbottest): Run an optional script pybuildbot.identify
to include some information about the build environment.
........
r57973 | matthias.klose | 2007-09-04 21:05:38 +0200 (Tue, 04 Sep 2007) | 2 lines
- Makefile.pre.in(buildbottest): Remove whitespace at eol.
........
r57975 | matthias.klose | 2007-09-04 22:46:02 +0200 (Tue, 04 Sep 2007) | 2 lines
- Fix libffi configure for hppa*-*-linux* | parisc*-*-linux*.
........
r57980 | bill.janssen | 2007-09-05 02:46:27 +0200 (Wed, 05 Sep 2007) | 1 line
SSL certificate distinguished names should be represented by tuples
........
r57985 | martin.v.loewis | 2007-09-05 08:39:17 +0200 (Wed, 05 Sep 2007) | 3 lines
Patch #1105: Explain that one needs to build the solution
to get dependencies right.
........
r57987 | armin.rigo | 2007-09-05 09:51:21 +0200 (Wed, 05 Sep 2007) | 4 lines
PyDict_GetItem() returns a borrowed reference.
There are probably a number of places that are open to attacks
such as the following one, in bltinmodule.c:min_max().
........
r57991 | martin.v.loewis | 2007-09-05 13:47:34 +0200 (Wed, 05 Sep 2007) | 3 lines
Patch #786737: Allow building in a tree of symlinks pointing to
a readonly source.
........
r57993 | georg.brandl | 2007-09-05 15:36:44 +0200 (Wed, 05 Sep 2007) | 2 lines
Backport from Py3k: Bug #1684991: explain lookup semantics for __special__ methods (new-style classes only).
........
r58004 | armin.rigo | 2007-09-06 10:30:51 +0200 (Thu, 06 Sep 2007) | 4 lines
Patch #1733973 by peaker:
ptrace_enter_call() assumes no exception is currently set.
This assumption is broken when throwing into a generator.
........
r58006 | armin.rigo | 2007-09-06 11:30:38 +0200 (Thu, 06 Sep 2007) | 4 lines
PyDict_GetItem() returns a borrowed reference.
This attack is against ceval.c:IMPORT_NAME, which calls an
object (__builtin__.__import__) without holding a reference to it.
........
r58013 | georg.brandl | 2007-09-06 16:49:56 +0200 (Thu, 06 Sep 2007) | 2 lines
Backport from 3k: #1116: fix reference to old filename.
........
r58021 | thomas.heller | 2007-09-06 22:26:20 +0200 (Thu, 06 Sep 2007) | 1 line
Fix typo: c_float represents to C float type.
........
r58022 | skip.montanaro | 2007-09-07 00:29:06 +0200 (Fri, 07 Sep 2007) | 3 lines
If this is correct for py3k branch and it's already in the release25-maint
branch, seems like it ought to be on the trunk as well.
........
r58023 | gregory.p.smith | 2007-09-07 00:59:59 +0200 (Fri, 07 Sep 2007) | 4 lines
Apply the fix from Issue1112 to make this test more robust and keep
windows happy.
........
r58031 | brett.cannon | 2007-09-07 05:17:50 +0200 (Fri, 07 Sep 2007) | 4 lines
Make uuid1 and uuid4 tests conditional on whether ctypes can be imported;
implementation of either function depends on ctypes but uuid as a whole does
not.
........
r58032 | brett.cannon | 2007-09-07 06:18:30 +0200 (Fri, 07 Sep 2007) | 6 lines
Fix a crasher where Python code managed to infinitely recurse in C code without
ever going back out to Python code in PyObject_Call(). Required introducing a
static RuntimeError instance so that normalizing an exception there is no
reliance on a recursive call that would put the exception system over the
recursion check itself.
........
r58034 | thomas.heller | 2007-09-07 08:32:17 +0200 (Fri, 07 Sep 2007) | 1 line
Add a 'c_longdouble' type to the ctypes module.
........
r58035 | thomas.heller | 2007-09-07 11:30:40 +0200 (Fri, 07 Sep 2007) | 1 line
Remove unneeded #include.
........
r58036 | thomas.heller | 2007-09-07 11:33:24 +0200 (Fri, 07 Sep 2007) | 6 lines
Backport from py3k branch:
Add a workaround for a strange bug on win64, when _ctypes is compiled
with the SDK compiler. This should fix the failing
Lib\ctypes\test\test_as_parameter.py test.
........
r58037 | georg.brandl | 2007-09-07 16:14:40 +0200 (Fri, 07 Sep 2007) | 2 lines
Fix a wrong indentation for sublists.
........
r58043 | georg.brandl | 2007-09-07 22:10:49 +0200 (Fri, 07 Sep 2007) | 2 lines
#1095: ln -f doesn't work portably, fix in Makefile.
........
r58049 | skip.montanaro | 2007-09-08 02:34:17 +0200 (Sat, 08 Sep 2007) | 1 line
be explicit about the actual location of the missing file
........
2007-09-08 14:39:28 -03:00
|
|
|
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
|
2007-08-15 11:28:22 -03:00
|
|
|
control sharing their global data space. For synchronization, simple locks
|
Merged revisions 57778-58052 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r57820 | georg.brandl | 2007-08-31 08:59:27 +0200 (Fri, 31 Aug 2007) | 2 lines
Document new shorthand notation for index entries.
........
r57827 | georg.brandl | 2007-08-31 10:47:51 +0200 (Fri, 31 Aug 2007) | 2 lines
Fix subitem markup.
........
r57833 | martin.v.loewis | 2007-08-31 12:01:07 +0200 (Fri, 31 Aug 2007) | 1 line
Mark registry components as 64-bit on Win64.
........
r57854 | bill.janssen | 2007-08-31 21:02:23 +0200 (Fri, 31 Aug 2007) | 1 line
deprecate use of FakeSocket
........
r57855 | bill.janssen | 2007-08-31 21:02:46 +0200 (Fri, 31 Aug 2007) | 1 line
remove mentions of socket.ssl in comments
........
r57856 | bill.janssen | 2007-08-31 21:03:31 +0200 (Fri, 31 Aug 2007) | 1 line
remove use of non-existent SSLFakeSocket in apparently untested code
........
r57859 | martin.v.loewis | 2007-09-01 08:36:03 +0200 (Sat, 01 Sep 2007) | 3 lines
Bug #1737210: Change Manufacturer of Windows installer to PSF.
Will backport to 2.5.
........
r57865 | georg.brandl | 2007-09-01 09:51:24 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix RST link (backport from Py3k).
........
r57876 | georg.brandl | 2007-09-01 17:49:49 +0200 (Sat, 01 Sep 2007) | 2 lines
Document sets' ">" and "<" operations (backport from py3k).
........
r57878 | skip.montanaro | 2007-09-01 19:40:03 +0200 (Sat, 01 Sep 2007) | 4 lines
Added a note and examples to explain that re.split does not split on an
empty pattern match. (issue 852532).
........
r57879 | walter.doerwald | 2007-09-01 20:18:09 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix wrong function names.
........
r57880 | walter.doerwald | 2007-09-01 20:34:05 +0200 (Sat, 01 Sep 2007) | 2 lines
Fix typo.
........
r57889 | andrew.kuchling | 2007-09-01 22:31:59 +0200 (Sat, 01 Sep 2007) | 1 line
Markup fix
........
r57892 | andrew.kuchling | 2007-09-01 22:43:36 +0200 (Sat, 01 Sep 2007) | 1 line
Add various items
........
r57895 | andrew.kuchling | 2007-09-01 23:17:58 +0200 (Sat, 01 Sep 2007) | 1 line
Wording change
........
r57896 | andrew.kuchling | 2007-09-01 23:18:31 +0200 (Sat, 01 Sep 2007) | 1 line
Add more items
........
r57904 | ronald.oussoren | 2007-09-02 11:46:07 +0200 (Sun, 02 Sep 2007) | 3 lines
Macosx: this patch ensures that the value of MACOSX_DEPLOYMENT_TARGET used
by the Makefile is also used at configure-time.
........
r57925 | georg.brandl | 2007-09-03 09:16:46 +0200 (Mon, 03 Sep 2007) | 2 lines
Fix #883466: don't allow Unicode as arguments to quopri and uu codecs.
........
r57936 | matthias.klose | 2007-09-04 01:33:04 +0200 (Tue, 04 Sep 2007) | 2 lines
- Added support for linking the bsddb module against BerkeleyDB 4.6.x.
........
r57954 | mark.summerfield | 2007-09-04 10:16:15 +0200 (Tue, 04 Sep 2007) | 3 lines
Added cross-references plus a note about dict & list shallow copying.
........
r57958 | martin.v.loewis | 2007-09-04 11:51:57 +0200 (Tue, 04 Sep 2007) | 3 lines
Document that we rely on the OS to release the crypto
context. Fixes #1626801.
........
r57960 | martin.v.loewis | 2007-09-04 15:13:14 +0200 (Tue, 04 Sep 2007) | 3 lines
Patch #1388440: Add set_completion_display_matches_hook and
get_completion_type to readline.
........
r57961 | martin.v.loewis | 2007-09-04 16:19:28 +0200 (Tue, 04 Sep 2007) | 3 lines
Patch #1031213: Decode source line in SyntaxErrors back to its original
source encoding. Will backport to 2.5.
........
r57972 | matthias.klose | 2007-09-04 20:17:36 +0200 (Tue, 04 Sep 2007) | 3 lines
- Makefile.pre.in(buildbottest): Run an optional script pybuildbot.identify
to include some information about the build environment.
........
r57973 | matthias.klose | 2007-09-04 21:05:38 +0200 (Tue, 04 Sep 2007) | 2 lines
- Makefile.pre.in(buildbottest): Remove whitespace at eol.
........
r57975 | matthias.klose | 2007-09-04 22:46:02 +0200 (Tue, 04 Sep 2007) | 2 lines
- Fix libffi configure for hppa*-*-linux* | parisc*-*-linux*.
........
r57980 | bill.janssen | 2007-09-05 02:46:27 +0200 (Wed, 05 Sep 2007) | 1 line
SSL certificate distinguished names should be represented by tuples
........
r57985 | martin.v.loewis | 2007-09-05 08:39:17 +0200 (Wed, 05 Sep 2007) | 3 lines
Patch #1105: Explain that one needs to build the solution
to get dependencies right.
........
r57987 | armin.rigo | 2007-09-05 09:51:21 +0200 (Wed, 05 Sep 2007) | 4 lines
PyDict_GetItem() returns a borrowed reference.
There are probably a number of places that are open to attacks
such as the following one, in bltinmodule.c:min_max().
........
r57991 | martin.v.loewis | 2007-09-05 13:47:34 +0200 (Wed, 05 Sep 2007) | 3 lines
Patch #786737: Allow building in a tree of symlinks pointing to
a readonly source.
........
r57993 | georg.brandl | 2007-09-05 15:36:44 +0200 (Wed, 05 Sep 2007) | 2 lines
Backport from Py3k: Bug #1684991: explain lookup semantics for __special__ methods (new-style classes only).
........
r58004 | armin.rigo | 2007-09-06 10:30:51 +0200 (Thu, 06 Sep 2007) | 4 lines
Patch #1733973 by peaker:
ptrace_enter_call() assumes no exception is currently set.
This assumption is broken when throwing into a generator.
........
r58006 | armin.rigo | 2007-09-06 11:30:38 +0200 (Thu, 06 Sep 2007) | 4 lines
PyDict_GetItem() returns a borrowed reference.
This attack is against ceval.c:IMPORT_NAME, which calls an
object (__builtin__.__import__) without holding a reference to it.
........
r58013 | georg.brandl | 2007-09-06 16:49:56 +0200 (Thu, 06 Sep 2007) | 2 lines
Backport from 3k: #1116: fix reference to old filename.
........
r58021 | thomas.heller | 2007-09-06 22:26:20 +0200 (Thu, 06 Sep 2007) | 1 line
Fix typo: c_float represents to C float type.
........
r58022 | skip.montanaro | 2007-09-07 00:29:06 +0200 (Fri, 07 Sep 2007) | 3 lines
If this is correct for py3k branch and it's already in the release25-maint
branch, seems like it ought to be on the trunk as well.
........
r58023 | gregory.p.smith | 2007-09-07 00:59:59 +0200 (Fri, 07 Sep 2007) | 4 lines
Apply the fix from Issue1112 to make this test more robust and keep
windows happy.
........
r58031 | brett.cannon | 2007-09-07 05:17:50 +0200 (Fri, 07 Sep 2007) | 4 lines
Make uuid1 and uuid4 tests conditional on whether ctypes can be imported;
implementation of either function depends on ctypes but uuid as a whole does
not.
........
r58032 | brett.cannon | 2007-09-07 06:18:30 +0200 (Fri, 07 Sep 2007) | 6 lines
Fix a crasher where Python code managed to infinitely recurse in C code without
ever going back out to Python code in PyObject_Call(). Required introducing a
static RuntimeError instance so that normalizing an exception there is no
reliance on a recursive call that would put the exception system over the
recursion check itself.
........
r58034 | thomas.heller | 2007-09-07 08:32:17 +0200 (Fri, 07 Sep 2007) | 1 line
Add a 'c_longdouble' type to the ctypes module.
........
r58035 | thomas.heller | 2007-09-07 11:30:40 +0200 (Fri, 07 Sep 2007) | 1 line
Remove unneeded #include.
........
r58036 | thomas.heller | 2007-09-07 11:33:24 +0200 (Fri, 07 Sep 2007) | 6 lines
Backport from py3k branch:
Add a workaround for a strange bug on win64, when _ctypes is compiled
with the SDK compiler. This should fix the failing
Lib\ctypes\test\test_as_parameter.py test.
........
r58037 | georg.brandl | 2007-09-07 16:14:40 +0200 (Fri, 07 Sep 2007) | 2 lines
Fix a wrong indentation for sublists.
........
r58043 | georg.brandl | 2007-09-07 22:10:49 +0200 (Fri, 07 Sep 2007) | 2 lines
#1095: ln -f doesn't work portably, fix in Makefile.
........
r58049 | skip.montanaro | 2007-09-08 02:34:17 +0200 (Sat, 08 Sep 2007) | 1 line
be explicit about the actual location of the missing file
........
2007-09-08 14:39:28 -03:00
|
|
|
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
|
|
|
|
The :mod:`threading` module provides an easier to use and higher-level
|
|
|
|
threading API built on top of this module.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. index::
|
|
|
|
single: pthreads
|
|
|
|
pair: threads; POSIX
|
|
|
|
|
2017-09-18 17:04:20 -03:00
|
|
|
.. versionchanged:: 3.7
|
|
|
|
This module used to be optional, it is now always available.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2017-09-18 17:04:20 -03:00
|
|
|
This module defines the following constants and functions:
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. exception:: error
|
|
|
|
|
|
|
|
Raised on thread-specific errors.
|
|
|
|
|
2011-02-28 18:03:34 -04:00
|
|
|
.. versionchanged:: 3.3
|
|
|
|
This is now a synonym of the built-in :exc:`RuntimeError`.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. data:: LockType
|
|
|
|
|
|
|
|
This is the type of lock objects.
|
|
|
|
|
|
|
|
|
|
|
|
.. function:: start_new_thread(function, args[, kwargs])
|
|
|
|
|
2019-05-28 21:57:56 -03:00
|
|
|
Start a new thread and return its identifier. The thread executes the
|
|
|
|
function *function* with the argument list *args* (which must be a tuple).
|
|
|
|
The optional *kwargs* argument specifies a dictionary of keyword arguments.
|
|
|
|
|
|
|
|
When the function returns, the thread silently exits.
|
|
|
|
|
|
|
|
When the function terminates with an unhandled exception,
|
|
|
|
:func:`sys.unraisablehook` is called to handle the exception. The *object*
|
|
|
|
attribute of the hook argument is *function*. By default, a stack trace is
|
|
|
|
printed and then the thread exits (but other threads continue to run).
|
|
|
|
|
|
|
|
When the function raises a :exc:`SystemExit` exception, it is silently
|
|
|
|
ignored.
|
|
|
|
|
2022-11-16 13:15:52 -04:00
|
|
|
.. audit-event:: _thread.start_new_thread function,args,kwargs start_new_thread
|
|
|
|
|
2019-05-28 21:57:56 -03:00
|
|
|
.. versionchanged:: 3.8
|
|
|
|
:func:`sys.unraisablehook` is now used to handle unhandled exceptions.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2021-03-11 18:35:45 -04:00
|
|
|
.. function:: interrupt_main(signum=signal.SIGINT, /)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2021-03-11 18:35:45 -04:00
|
|
|
Simulate the effect of a signal arriving in the main thread.
|
|
|
|
A thread can use this function to interrupt the main thread, though
|
|
|
|
there is no guarantee that the interruption will happen immediately.
|
2019-05-23 17:30:00 -03:00
|
|
|
|
2021-03-11 18:35:45 -04:00
|
|
|
If given, *signum* is the number of the signal to simulate.
|
2023-07-21 06:40:37 -03:00
|
|
|
If *signum* is not given, :const:`signal.SIGINT` is simulated.
|
2021-03-11 18:35:45 -04:00
|
|
|
|
|
|
|
If the given signal isn't handled by Python (it was set to
|
2023-07-21 06:40:37 -03:00
|
|
|
:const:`signal.SIG_DFL` or :const:`signal.SIG_IGN`), this function does
|
2019-05-23 17:30:00 -03:00
|
|
|
nothing.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2021-03-11 18:35:45 -04:00
|
|
|
.. versionchanged:: 3.10
|
|
|
|
The *signum* argument is added to customize the signal number.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
This does not emit the corresponding signal but schedules a call to
|
|
|
|
the associated handler (if it exists).
|
|
|
|
If you want to truly emit the signal, use :func:`signal.raise_signal`.
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
.. function:: exit()
|
|
|
|
|
|
|
|
Raise the :exc:`SystemExit` exception. When not caught, this will cause the
|
|
|
|
thread to exit silently.
|
|
|
|
|
Merged revisions 59605-59624 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines
Some cleanup in the docs.
........
r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines
Bug #1699: Define _BSD_SOURCE only on OpenBSD.
........
r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line
Simpler documentation for itertools.tee(). Should be backported.
........
r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line
Improve docs for itertools.groupby(). The use of xrange(0) to create a unique object is less obvious than object().
........
r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines
Added wininst-9.0.exe executable for VS 2008
Integrated bdist_wininst into PCBuild9 directory
........
r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line
Moved PCbuild directory to PC/VS7.1
........
r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line
Fix paths for build bot
........
r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line
Fix paths for build bot, part 2
........
r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line
Renamed PCBuild9 directory to PCBuild
........
2007-12-31 12:14:33 -04:00
|
|
|
..
|
|
|
|
function:: exit_prog(status)
|
|
|
|
|
|
|
|
Exit all threads and report the value of the integer argument
|
|
|
|
*status* as the exit status of the entire program.
|
|
|
|
**Caveat:** code in pending :keyword:`finally` clauses, in this thread
|
|
|
|
or in other threads, is not executed.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
|
|
|
.. function:: allocate_lock()
|
|
|
|
|
|
|
|
Return a new lock object. Methods of locks are described below. The lock is
|
|
|
|
initially unlocked.
|
|
|
|
|
|
|
|
|
|
|
|
.. function:: get_ident()
|
|
|
|
|
|
|
|
Return the 'thread identifier' of the current thread. This is a nonzero
|
|
|
|
integer. Its value has no direct meaning; it is intended as a magic cookie to
|
|
|
|
be used e.g. to index a dictionary of thread-specific data. Thread identifiers
|
|
|
|
may be recycled when a thread exits and another thread is created.
|
|
|
|
|
|
|
|
|
2019-05-22 12:43:17 -03:00
|
|
|
.. function:: get_native_id()
|
|
|
|
|
|
|
|
Return the native integral Thread ID of the current thread assigned by the kernel.
|
|
|
|
This is a non-negative integer.
|
|
|
|
Its value may be used to uniquely identify this particular thread system-wide
|
|
|
|
(until the thread terminates, after which the value may be recycled by the OS).
|
|
|
|
|
2023-11-09 16:02:30 -04:00
|
|
|
.. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD.
|
2019-05-22 12:43:17 -03:00
|
|
|
|
|
|
|
.. versionadded:: 3.8
|
|
|
|
|
2023-11-09 16:02:30 -04:00
|
|
|
.. versionchanged:: 3.13
|
|
|
|
Added support for GNU/kFreeBSD.
|
|
|
|
|
2019-05-22 12:43:17 -03:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
.. function:: stack_size([size])
|
|
|
|
|
|
|
|
Return the thread stack size used when creating new threads. The optional
|
|
|
|
*size* argument specifies the stack size to be used for subsequently created
|
|
|
|
threads, and must be 0 (use platform or configured default) or a positive
|
2015-08-31 00:15:52 -03:00
|
|
|
integer value of at least 32,768 (32 KiB). If *size* is not specified,
|
|
|
|
0 is used. If changing the thread stack size is
|
2012-04-05 04:53:04 -03:00
|
|
|
unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is
|
2013-02-16 11:29:56 -04:00
|
|
|
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB
|
2007-08-15 11:28:22 -03:00
|
|
|
is currently the minimum supported stack size value to guarantee sufficient
|
|
|
|
stack space for the interpreter itself. Note that some platforms may have
|
|
|
|
particular restrictions on values for the stack size, such as requiring a
|
2013-02-16 11:29:56 -04:00
|
|
|
minimum stack size > 32 KiB or requiring allocation in multiples of the system
|
2007-08-15 11:28:22 -03:00
|
|
|
memory page size - platform documentation should be referred to for more
|
2013-02-16 11:29:56 -04:00
|
|
|
information (4 KiB pages are common; using multiples of 4096 for the stack size is
|
2007-08-15 11:28:22 -03:00
|
|
|
the suggested approach in the absence of more specific information).
|
2018-10-12 11:55:20 -03:00
|
|
|
|
2022-07-29 11:42:09 -03:00
|
|
|
.. availability:: Windows, pthreads.
|
|
|
|
|
|
|
|
Unix platforms with POSIX threads support.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
|
2010-04-14 12:44:10 -03:00
|
|
|
.. data:: TIMEOUT_MAX
|
|
|
|
|
|
|
|
The maximum value allowed for the *timeout* parameter of
|
2023-07-23 06:23:44 -03:00
|
|
|
:meth:`Lock.acquire <threading.Lock.acquire>`. Specifying a timeout greater
|
|
|
|
than this value will raise an :exc:`OverflowError`.
|
2010-04-14 12:44:10 -03:00
|
|
|
|
2010-04-19 11:05:51 -03:00
|
|
|
.. versionadded:: 3.2
|
|
|
|
|
2010-04-14 12:44:10 -03:00
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
Lock objects have the following methods:
|
|
|
|
|
|
|
|
|
2022-10-04 19:18:04 -03:00
|
|
|
.. method:: lock.acquire(blocking=True, timeout=-1)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-04-14 12:44:10 -03:00
|
|
|
Without any optional argument, this method acquires the lock unconditionally, if
|
2007-08-15 11:28:22 -03:00
|
|
|
necessary waiting until it is released by another thread (only one thread at a
|
2010-04-14 12:44:10 -03:00
|
|
|
time can acquire a lock --- that's their reason for existence).
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2022-10-04 19:18:04 -03:00
|
|
|
If the *blocking* argument is present, the action depends on its
|
2024-05-08 16:35:16 -03:00
|
|
|
value: if it is false, the lock is only acquired if it can be acquired
|
|
|
|
immediately without waiting, while if it is true, the lock is acquired
|
2010-04-14 12:44:10 -03:00
|
|
|
unconditionally as above.
|
|
|
|
|
|
|
|
If the floating-point *timeout* argument is present and positive, it
|
|
|
|
specifies the maximum wait time in seconds before returning. A negative
|
|
|
|
*timeout* argument specifies an unbounded wait. You cannot specify
|
2024-05-08 16:35:16 -03:00
|
|
|
a *timeout* if *blocking* is false.
|
2010-04-14 12:44:10 -03:00
|
|
|
|
|
|
|
The return value is ``True`` if the lock is acquired successfully,
|
|
|
|
``False`` if not.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2010-04-19 11:05:51 -03:00
|
|
|
.. versionchanged:: 3.2
|
|
|
|
The *timeout* parameter is new.
|
|
|
|
|
2010-12-15 18:59:16 -04:00
|
|
|
.. versionchanged:: 3.2
|
|
|
|
Lock acquires can now be interrupted by signals on POSIX.
|
|
|
|
|
|
|
|
|
2007-08-15 11:28:22 -03:00
|
|
|
.. method:: lock.release()
|
|
|
|
|
|
|
|
Releases the lock. The lock must have been acquired earlier, but not
|
|
|
|
necessarily by the same thread.
|
|
|
|
|
|
|
|
|
|
|
|
.. method:: lock.locked()
|
|
|
|
|
|
|
|
Return the status of the lock: ``True`` if it has been acquired by some thread,
|
|
|
|
``False`` if not.
|
|
|
|
|
|
|
|
In addition to these methods, lock objects can also be used via the
|
|
|
|
:keyword:`with` statement, e.g.::
|
|
|
|
|
2008-05-25 10:05:15 -03:00
|
|
|
import _thread
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2008-05-25 10:05:15 -03:00
|
|
|
a_lock = _thread.allocate_lock()
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
with a_lock:
|
2007-09-01 20:34:30 -03:00
|
|
|
print("a_lock is locked while this executes")
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
**Caveats:**
|
|
|
|
|
2023-10-11 17:24:12 -03:00
|
|
|
.. index:: pair: module; signal
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2024-10-06 19:57:03 -03:00
|
|
|
* Interrupts always go to the main thread (the :exc:`KeyboardInterrupt`
|
|
|
|
exception will be received by that thread.)
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
|
Merged revisions 74542,74544-74548,74550,74554-74555,74578,74588,74590,74603,74616-74618,74621 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r74542 | georg.brandl | 2009-08-23 23:28:56 +0200 (So, 23 Aug 2009) | 1 line
Restore alphabetic order.
........
r74544 | georg.brandl | 2009-08-24 19:12:30 +0200 (Mo, 24 Aug 2009) | 1 line
#6775: fix python.org URLs in README.
........
r74545 | georg.brandl | 2009-08-24 19:14:29 +0200 (Mo, 24 Aug 2009) | 1 line
#6772: mention utf-8 as utf8 alias.
........
r74546 | georg.brandl | 2009-08-24 19:20:40 +0200 (Mo, 24 Aug 2009) | 1 line
#6725: spell "namespace" consistently.
........
r74547 | georg.brandl | 2009-08-24 19:22:05 +0200 (Mo, 24 Aug 2009) | 1 line
#6718: fix example.
........
r74548 | georg.brandl | 2009-08-24 19:24:27 +0200 (Mo, 24 Aug 2009) | 1 line
#6677: mention "deleting" as an alias for removing files.
........
r74550 | georg.brandl | 2009-08-24 19:48:40 +0200 (Mo, 24 Aug 2009) | 1 line
#6677: note that rmdir only removes empty directories.
........
r74554 | georg.brandl | 2009-08-27 20:59:02 +0200 (Do, 27 Aug 2009) | 1 line
Typo fix.
........
r74555 | georg.brandl | 2009-08-27 21:02:43 +0200 (Do, 27 Aug 2009) | 1 line
#6787: reference fix.
........
r74578 | tarek.ziade | 2009-08-29 15:33:21 +0200 (Sa, 29 Aug 2009) | 1 line
fixed #6801: symmetric_difference_update also accepts pipe
........
r74588 | georg.brandl | 2009-08-30 10:35:01 +0200 (So, 30 Aug 2009) | 1 line
#6803: fix old name.
........
r74590 | georg.brandl | 2009-08-30 13:51:53 +0200 (So, 30 Aug 2009) | 1 line
#6801: fix copy-paste oversight.
........
r74603 | georg.brandl | 2009-08-31 08:38:29 +0200 (Mo, 31 Aug 2009) | 1 line
other -> others where multiple arguments are accepted.
........
r74616 | georg.brandl | 2009-09-01 09:46:26 +0200 (Di, 01 Sep 2009) | 1 line
#6808: clarification.
........
r74617 | georg.brandl | 2009-09-01 09:53:37 +0200 (Di, 01 Sep 2009) | 1 line
#6765: hint that log(x, base) is not very sophisticated.
........
r74618 | georg.brandl | 2009-09-01 10:00:47 +0200 (Di, 01 Sep 2009) | 1 line
#6810: add a link to the section about frame objects instead of just a description where to find it.
........
r74621 | georg.brandl | 2009-09-01 10:06:03 +0200 (Di, 01 Sep 2009) | 1 line
#6638: fix wrong parameter name and markup a class.
........
2009-09-01 05:11:14 -03:00
|
|
|
equivalent to calling :func:`_thread.exit`.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
2024-10-11 05:15:46 -03:00
|
|
|
* It is platform-dependent whether the :meth:`~threading.Lock.acquire` method
|
|
|
|
on a lock can be interrupted (so that the :exc:`KeyboardInterrupt` exception
|
|
|
|
will happen immediately, rather than only after the lock has been acquired or
|
|
|
|
the operation has timed out). It can be interrupted on POSIX, but not on
|
|
|
|
Windows.
|
2007-08-15 11:28:22 -03:00
|
|
|
|
|
|
|
* When the main thread exits, it is system defined whether the other threads
|
2010-04-19 11:09:57 -03:00
|
|
|
survive. On most systems, they are killed without executing
|
|
|
|
:keyword:`try` ... :keyword:`finally` clauses or executing object
|
|
|
|
destructors.
|
2007-08-15 11:28:22 -03:00
|
|
|
|