8000 make patchcheck · python/cpython@a8b7b1a · GitHub
[go: up one dir, main page]
Skip to content

Commit a8b7b1a

Browse files
YvesDupYvesDup
committed
make patchcheck
run make patchcheck
1 parent bc3d17a commit a8b7b1a

20 files changed

+15457
-0
lines changed

‎Doc/c-api/exceptions.rst.bak

Lines changed: 1054 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/c-api/memory.rst.bak

Lines changed: 642 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/faq/design.rst.bak

Lines changed: 759 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/howto/descriptor.rst.bak

Lines changed: 1575 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/library/_thread.rst.bak

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
:mod:`_thread` --- Low-level threading API
2+
==========================================
3+
4+
.. module:: _thread
5+
:synopsis: Low-level threading API.
6+
7+
.. index::
8+
single: light-weight processes
9+
single: processes, light-weight
10+
single: binary semaphores
11+
single: semaphores, binary
12+
13+
--------------
14+
15+
This module provides low-level primitives for working with multiple threads
16+
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
17+
control sharing their global data space. For synchronization, simple locks
18+
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
19+
The :mod:`threading` module provides an easier to use and higher-level
20+
threading API built on top of this module.
21+
22+
.. index::
23+
single: pthreads
24+
pair: threads; POSIX
25+
26+
.. versionchanged:: 3.7
27+
This module used to be optional, it is now always available.
28+
29+
This module defines the following constants and functions:
30+
31+
.. exception:: error
32+
33+
Raised on thread-specific errors.
34+
35+
.. versionchanged:: 3.3
36+
This is now a synonym of the built-in :exc:`RuntimeError`.
37+
38+
39+
.. data:: LockType
40+
41+
This is the type of lock objects.
42+
43+
44+
.. function:: start_new_thread(function, args[, kwargs])
45+
46+
Start a new thread and return its identifier. The thread executes the
47+
function *function* with the argument list *args* (which must be a tuple).
48+
The optional *kwargs* argument specifies a dictionary of keyword arguments.
49+
50+
When the function returns, the thread silently exits.
51+
52+
When the function terminates with an unhandled exception,
53+
:func:`sys.unraisablehook` is called to handle the exception. The *object*
54+
attribute of the hook argument is *function*. By default, a stack trace is
55+
printed and then the thread exits (but other threads continue to run).
56+
57+
When the function raises a :exc:`SystemExit` exception, it is silently
58+
ignored.
59+
60+
.. versionchanged:: 3.8
61+
:func:`sys.unraisablehook` is now used to handle unhandled exceptions.
62+
63+
64+
.. function:: interrupt_main()
65+
66+
Simulate the effect of a :data:`signal.SIGINT` signal arriving in the main
67+
thread. A thread can use this function to interrupt the main thread.
68+
69+
If :data:`signal.SIGINT` isn't handled by Python (it was set to
70+
:data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
71+
nothing.
72+
73+
74+
.. function:: exit()
75+
76+
Raise the :exc:`SystemExit` exception. When not caught, this will cause the
77+
thread to exit silently.
78+
79+
..
80+
function:: exit_prog(status)
81+
82+
Exit all threads and report the value of the integer argument
83+
*status* as the exit status of the entire program.
84+
**Caveat:** code in pending :keyword:`finally` clauses, in this thread
85+
or in other threads, is not executed.
86+
87+
88+
.. function:: allocate_lock()
89+
90+
Return a new lock object. Methods of locks are described below. The lock is
91+
initially unlocked.
92+
93+
94+
.. function:: get_ident()
95+
96+
Return the 'thread identifier' of the current thread. This is a nonzero
97+
integer. Its value has no direct meaning; it is intended as a magic cookie to
98+
be used e.g. to index a dictionary of thread-specific data. Thread identifiers
99+
may be recycled when a thread exits and another thread is created.
100+
101+
102+
.. function:: get_native_id()
103+
104+
Return the native integral Thread ID of the current thread assigned by the kernel.
105+
This is a non-negative integer.
106+
Its value may be used to uniquely identify this particular thread system-wide
107+
(until the thread terminates, after which the value may be recycled by the OS).
108+
109+
.. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX.
110+
111+
.. versionadded:: 3.8
112+
113+
114+
.. function:: stack_size([size])
115+
116+
Return the thread stack size used when creating new threads. The optional
117+
*size* argument specifies the stack size to be used for subsequently created
118+
threads, and must be 0 (use platform or configured default) or a positive
119+
integer value of at least 32,768 (32 KiB). If *size* is not specified,
120+
0 is used. If changing the thread stack size is
121+
unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is
122+
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB
123+
is currently the minimum supported stack size value to guarantee sufficient
124+
stack space for the interpreter itself. Note that some platforms may have
125+
particular restrictions on values for the stack size, such as requiring a
126+
minimum stack size > 32 KiB or requiring allocation in multiples of the system
127+
memory page size - platform documentation should be referred to for more
128+
information (4 KiB pages are common; using multiples of 4096 for the stack size is
129+
the suggested approach in the absence of more specific information).
130+
131+
.. availability:: Windows, systems with POSIX threads.
132+
133+
134+
.. data:: TIMEOUT_MAX
135+
136+
The maximum value allowed for the *timeout* parameter of
137+
:meth:`Lock.acquire`. Specifying a timeout greater than this value will
138+
raise an :exc:`OverflowError`.
139+
140+
.. versionadded:: 3.2
141+
142+
143+
Lock objects have the following methods:
144+
145+
146+
.. method:: lock.acquire(waitflag=1, timeout=-1)
147+
148+
Without any optional argument, this method acquires the lock unconditionally, if
149+
necessary waiting until it is released by another thread (only one thread at a
150+
time can acquire a lock --- that's their reason for existence).
151+
152+
If the integer *waitflag* argument is present, the action depends on its
153+
value: if it is zero, the lock is only acquired if it can be acquired
154+
immediately without waiting, while if it is nonzero, the lock is acquired
155+
unconditionally as above.
156+
157+
If the floating-point *timeout* argument is present and positive, it
158+
specifies the maximum wait time in seconds before returning. A negative
159+
*timeout* argument specifies an unbounded wait. You cannot specify
160+
a *timeout* if *waitflag* is zero.
161+
162+
The return value is ``True`` if the lock is acquired successfully,
163+
``False`` if not.
164+
165+
.. versionchanged:: 3.2
166+
The *timeout* parameter is new.
167+
168+
.. versionchanged:: 3.2
169+
Lock acquires can now be interrupted by signals on POSIX.
170+
171+
172+
.. method:: lock.release()
173+
174+
Releases the lock. The lock must have been acquired earlier, but not
175+
necessarily by the same thread.
176+
177+
178+
.. method:: lock.locked()
179+
180+
Return the status of the lock: ``True`` if it has been acquired by some thread,
181+
``False`` if not.
182+
183+
In addition to these methods, lock objects can also be used via the
184+
:keyword:`with` statement, e.g.::
185+
186+
import _thread
187+
188+
a_lock = _thread.allocate_lock()
189+
190+
with a_lock:
191+
print("a_lock is locked while this executes")
192+
193+
**Caveats:**
194+
195+
.. index:: module: signal
196+
197+
* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
198+
exception will be received by an arbitrary thread. (When the :mod:`signal`
199+
module is available, interrupts always go to the main thread.)
200+
201+
* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
202+
equivalent to calling :func:`_thread.exit`.
203+
204+
* It is not possible to interrupt the :meth:`acquire` method on a lock --- the
205+
:exc:`KeyboardInterrupt` exception will happen after the lock has been acquired.
206+
207+
* When the main thread exits, it is system defined whether the other threads
208+
survive. On most systems, they are killed without executing
209+
:keyword:`try` ... :keyword:`finally` clauses or executing object
210+
destructors.
211+
212+
* When the main thread exits, it does not do any of its usual cleanup (except
213+
that :keyword:`try` ... :keyword:`finally` clauses are honored), and the
214+
standard I/O files are not flushed.
215+

0 commit comments

Comments
 (0)
0