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

Skip to content

Commit 9e0ae53

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #18757: Improved cross-references in the concurrent package.
1 parent 78ede7c commit 9e0ae53

6 files changed

Lines changed: 91 additions & 77 deletions

File tree

‎Doc/library/concurrent.futures.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Executor Objects
4040

4141
.. method:: map(func, *iterables, timeout=None)
4242

43-
Equivalent to ``map(func, *iterables)`` except *func* is executed
43+
Equivalent to :func:`map(func, *iterables) <map>` except *func* is executed
4444
asynchronously and several calls to *func* may be made concurrently. The
4545
returned iterator raises a :exc:`TimeoutError` if
4646
:meth:`~iterator.__next__` is called and the result isn't available

‎Doc/library/multiprocessing.rst‎

Lines changed: 52 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -386,7 +386,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the
386386
Unix daemons or services, they are normal processes that will be
387387
terminated (and not joined) if non-daemonic processes have exited.
388388

389-
In addition to the :class:`Threading.Thread` API, :class:`Process` objects
389+
In addition to the :class:`threading.Thread` API, :class:`Process` objects
390390
also support the following attributes and methods:
391391

392392
.. attribute:: pid
@@ -405,7 +405,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the
405405
The process's authentication key (a byte string).
406406

407407
When :mod:`multiprocessing` is initialized the main process is assigned a
408-
random string using :func:`os.random`.
408+
random string using :func:`os.urandom`.
409409

410410
When a :class:`Process` object is created, it will inherit the
411411
authentication key of its parent process, although this may be changed by
@@ -530,7 +530,7 @@ Note that one can also create a shared queue by using a manager object -- see
530530
(1) After putting an object on an empty queue there may be an
531531
infinitesimal delay before the queue's :meth:`~Queue.empty`
532532
method returns :const:`False` and :meth:`~Queue.get_nowait` can
533-
return without raising :exc:`Queue.Empty`.
533+
return without raising :exc:`queue.Empty`.
534534

535535
(2) If multiple processes are enqueuing objects, it is possible for
536536
the objects to be received at the other end out-of-order.
@@ -547,7 +547,8 @@ Note that one can also create a shared queue by using a manager object -- see
547547
.. warning::
548548

549549
As mentioned above, if a child process has put items on a queue (and it has
550-
not used :meth:`JoinableQueue.cancel_join_thread`), then that process will
550+
not used :meth:`JoinableQueue.cancel_join_thread
551+
<multiprocessing.Queue.cancel_join_thread>`), then that process will
551552
not terminate until all buffered items have been flushed to the pipe.
552553

553554
This means that if you try joining that process you may get a deadlock unless
@@ -580,7 +581,7 @@ For an example of the usage of queues for interprocess communication see
580581
thread is started which transfers objects from a buffer into the pipe.
581582

582583
The usual :exc:`queue.Empty` and :exc:`queue.Full` exceptions from the
583-
standard library's :mod:`Queue` module are raised to signal timeouts.
584+
standard library's :mod:`queue` module are raised to signal timeouts.
584585

585586
:class:`Queue` implements all the methods of :class:`queue.Queue` except for
586587
:meth:`~queue.Queue.task_done` and :meth:`~queue.Queue.join`.
@@ -696,7 +697,7 @@ For an example of the usage of queues for interprocess communication see
696697
call to :meth:`task_done` tells the queue that the processing on the task
697698
is complete.
698699

699-
If a :meth:`~Queue.join` is currently blocking, it will resume when all
700+
If a :meth:`~queue.Queue.join` is currently blocking, it will resume when all
700701
items have been processed (meaning that a :meth:`task_done` call was
701702
received for every item that had been :meth:`~Queue.put` into the queue).
702703

@@ -712,7 +713,7 @@ For an example of the usage of queues for interprocess communication see
712713
queue. The count goes down whenever a consumer calls
713714
:meth:`task_done` to indicate that the item was retrieved and all work on
714715
it is complete. When the count of unfinished tasks drops to zero,
715-
:meth:`~Queue.join` unblocks.
716+
:meth:`~queue.Queue.join` unblocks.
716717

717718

718719
Miscellaneous
@@ -874,8 +875,8 @@ Connection objects are usually created using :func:`Pipe` -- see also
874875

875876
.. versionadded:: 3.3
876877
Connection objects now support the context manager protocol -- see
877-
:ref:`typecontextmanager`. :meth:`__enter__` returns the
878-
connection object, and :meth:`__exit__` calls :meth:`close`.
878+
:ref:`typecontextmanager`. :meth:`~contextmanager.__enter__` returns the
879+
connection object, and :meth:`~contextmanager.__exit__` calls :meth:`close`.
879880

880881
For example:
881882

@@ -948,7 +949,7 @@ object -- see :ref:`multiprocessing-managers`.
948949
object from :mod:`multiprocessing`.
949950

950951
.. versionchanged:: 3.3
951-
The :meth:`wait_for` method was added.
952+
The :meth:`~threading.Condition.wait_for` method was added.
952953

953954
.. class:: Event()
954955

@@ -1095,8 +1096,9 @@ processes.
10951096
array.
10961097

10971098
If *lock* is ``True`` (the default) then a new lock object is created to
1098-
synchronize access to the value. If *lock* is a :class:`Lock` or
1099-
:class:`RLock` object then that will be used to synchronize access to the
1099+
synchronize access to the value. If *lock* is a
1100+
:class:`~multiprocessing.Lock` or :class:`~multiprocessing.RLock` object
1101+
then that will be used to synchronize access to the
11001102
value. If *lock* is ``False`` then access to the returned object will not be
11011103
automatically protected by a lock, so it will not necessarily be
11021104
"process-safe".
@@ -1110,8 +1112,8 @@ processes.
11101112
object.
11111113

11121114
If *lock* is ``True`` (the default) then a new lock object is created to
1113-
synchronize access to the value. If *lock* is a :class:`Lock` or
1114-
:class:`RLock` object then that will be used to synchronize access to the
1115+
synchronize access to the value. If *lock* is a :class:`~multiprocessing.Lock` or
1116+
:class:`~multiprocessing.RLock` object then that will be used to synchronize access to the
11151117
value. If *lock* is ``False`` then access to the returned object will not be
11161118
automatically protected by a lock, so it will not necessarily be
11171119
"process-safe".
@@ -1296,8 +1298,8 @@ their parent process exits. The manager classes are defined in the
12961298
:attr:`proxytype._exposed_` is used instead if it exists.) In the case
12971299
where no exposed list is specified, all "public methods" of the shared
12981300
object will be accessible. (Here a "public method" means any attribute
1299-
which has a :meth:`__call__` method and whose name does not begin with
1300-
``'_'``.)
1301+
which has a :meth:`~object.__call__` method and whose name does not begin
1302+
with ``'_'``.)
13011303

13021304
*method_to_typeid* is a mapping used to specify the return type of those
13031305
exposed methods which should return a proxy. It maps method names to
@@ -1318,11 +1320,11 @@ their parent process exits. The manager classes are defined in the
13181320

13191321
.. versionchanged:: 3.3
13201322
Manager objects support the context manager protocol -- see
1321-
:ref:`typecontextmanager`. :meth:`__enter__` starts the server
1322-
process (if it has not already started) and then returns the
1323-
manager object. :meth:`__exit__` calls :meth:`shutdown`.
1323+
:ref:`typecontextmanager`. :meth:`~contextmanager.__enter__` starts the
1324+
server process (if it has not already started) and then returns the
1325+
manager object. :meth:`~contextmanager.__exit__` calls :meth:`shutdown`.
13241326

1325-
In previous versions :meth:`__enter__` did not start the
1327+
In previous versions :meth:`~contextmanager.__enter__` did not start the
13261328
manager's server process if it was not already started.
13271329

13281330
.. class:: SyncManager
@@ -1354,7 +1356,7 @@ their parent process exits. The manager classes are defined in the
13541356
:class:`threading.Lock` or :class:`threading.RLock` object.
13551357

13561358
.. versionchanged:: 3.3
1357-
The :meth:`wait_for` method was added.
1359+
The :meth:`~threading.Condition.wait_for` method was added.
13581360

13591361
.. method:: Event()
13601362

@@ -1798,8 +1800,8 @@ with the :class:`Pool` class.
17981800

17991801
.. versionadded:: 3.3
18001802
Pool objects now support the context manager protocol -- see
1801-
:ref:`typecontextmanager`. :meth:`__enter__` returns the pool
1802-
object, and :meth:`__exit__` calls :meth:`terminate`.
1803+
:ref:`typecontextmanager`. :meth:`~contextmanager.__enter__` returns the
1804+
pool object, and :meth:~contextmanager.`__exit__` calls :meth:`terminate`.
18031805

18041806

18051807
.. class:: AsyncResult
@@ -1860,7 +1862,8 @@ Listeners and Clients
18601862
:synopsis: API for dealing with sockets.
18611863

18621864
Usually message passing between processes is done using queues or by using
1863-
:class:`Connection` objects returned by :func:`Pipe`.
1865+
:class:`~multiprocessing.Connection` objects returned by
1866+
:func:`~multiprocessing.Pipe`.
18641867

18651868
However, the :mod:`multiprocessing.connection` module allows some extra
18661869
flexibility. It basically gives a high level message oriented API for dealing
@@ -1928,7 +1931,8 @@ multiple connections at the same time.
19281931
private temporary directory created using :func:`tempfile.mkstemp`.
19291932

19301933
If the listener object uses a socket then *backlog* (1 by default) is passed
1931-
to the :meth:`listen` method of the socket once it has been bound.
1934+
to the :meth:`~socket.socket.listen` method of the socket once it has been
1935+
bound.
19321936

19331937
If *authenticate* is ``True`` (``False`` by default) or *authkey* is not
19341938
``None`` then digest authentication is used.
@@ -1946,8 +1950,8 @@ multiple connections at the same time.
19461950
.. method:: accept()
19471951

19481952
Accept a connection on the bound socket or named pipe of the listener
1949-
object and return a :class:`Connection` object. If authentication is
1950-
attempted and fails, then
1953+
object and return a :class:`~multiprocessing.Connection` object. If
1954+
authentication is attempted and fails, then
19511955
:exc:`~multiprocessing.AuthenticationError` is raised.
19521956

19531957
.. method:: close()
@@ -1969,8 +1973,8 @@ multiple connections at the same time.
19691973

19701974
.. versionadded:: 3.3
19711975
Listener objects now support the context manager protocol -- see
1972-
:ref:`typecontextmanager`. :meth:`__enter__` returns the
1973-
listener object, and :meth:`__exit__` calls :meth:`close`.
1976+
:ref:`typecontextmanager`. :meth:`~contextmanager.__enter__` returns the
1977+
listener object, and :meth:~contextmanager.`__exit__` calls :meth:`close`.
19741978

19751979
.. function:: wait(object_list, timeout=None)
19761980

@@ -2106,7 +2110,8 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address.
21062110
Authentication keys
21072111
~~~~~~~~~~~~~~~~~~~
21082112

2109-
When one uses :meth:`Connection.recv`, the data received is automatically
2113+
When one uses :meth:`Connection.recv <multiprocessing.Connection.recv>`, the
2114+
data received is automatically
21102115
unpickled. Unfortunately unpickling data from an untrusted source is a security
21112116
risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module
21122117
to provide digest authentication.
@@ -2256,9 +2261,10 @@ Joining zombie processes
22562261

22572262
On Unix when a process finishes but has not been joined it becomes a zombie.
22582263
There should never be very many because each time a new process starts (or
2259-
:func:`active_children` is called) all completed processes which have not
2260-
yet been joined will be joined. Also calling a finished process's
2261-
:meth:`Process.is_alive` will join the process. Even so it is probably good
2264+
:func:`~multiprocessing.active_children` is called) all completed processes
2265+
which have not yet been joined will be joined. Also calling a finished
2266+
process's :meth:`Process.is_alive <multiprocessing.Process.is_alive>` will
2267+
join the process. Even so it is probably good
22622268
practice to explicitly join all the processes that you start.
22632269

22642270
Better to inherit than pickle/unpickle
@@ -2271,20 +2277,23 @@ Better to inherit than pickle/unpickle
22712277

22722278
Avoid terminating processes
22732279

2274-
Using the :meth:`Process.terminate` method to stop a process is liable to
2280+
Using the :meth:`Process.terminate <multiprocessing.Process.terminate>`
2281+
method to stop a process is liable to
22752282
cause any shared resources (such as locks, semaphores, pipes and queues)
22762283
currently being used by the process to become broken or unavailable to other
22772284
processes.
22782285

22792286
Therefore it is probably best to only consider using
2280-
:meth:`Process.terminate` on processes which never use any shared resources.
2287+
:meth:`Process.terminate <multiprocessing.Process.terminate>` on processes
2288+
which never use any shared resources.
22812289

22822290
Joining processes that use queues
22832291

22842292
Bear in mind that a process that has put items in a queue will wait before
22852293
terminating until all the buffered items are fed by the "feeder" thread to
22862294
the underlying pipe. (The child process can call the
2287-
:meth:`Queue.cancel_join_thread` method of the queue to avoid this behaviour.)
2295+
:meth:`Queue.cancel_join_thread <multiprocessing.Queue.cancel_join_thread>`
2296+
method of the queue to avoid this behaviour.)
22882297

22892298
This means that whenever you use a queue you need to make sure that all
22902299
items which have been put on the queue will eventually be removed before the
@@ -2361,7 +2370,7 @@ Beware of replacing :data:`sys.stdin` with a "file like object"
23612370
resulting in a bad file descriptor error, but introduces a potential danger
23622371
to applications which replace :func:`sys.stdin` with a "file-like object"
23632372
with output buffering. This danger is that if multiple processes call
2364-
:func:`close()` on this file-like object, it could result in the same
2373+
:meth:`~io.IOBase.close()` on this file-like object, it could result in the same
23652374
data being flushed to the object multiple times, resulting in corruption.
23662375

23672376
If you write a file-like object and implement your own caching, you can
@@ -2390,14 +2399,16 @@ More picklability
23902399
as the ``target`` argument on Windows --- just define a function and use
23912400
that instead.
23922401

2393-
Also, if you subclass :class:`Process` then make sure that instances will be
2394-
picklable when the :meth:`Process.start` method is called.
2402+
Also, if you subclass :class:`~multiprocessing.Process` then make sure that
2403+
instances will be picklable when the :meth:`Process.start
2404+
<multiprocessing.Process.start>` method is called.
23952405

23962406
Global variables
23972407

23982408
Bear in mind that if code run in a child process tries to access a global
23992409
variable, then the value it sees (if any) may not be the same as the value
2400-
in the parent process at the time that :meth:`Process.start` was called.
2410+
in the parent process at the time that :meth:`Process.start
2411+
<multiprocessing.Process.start>` was called.
24012412

24022413
However, global variables which are just module level constants cause no
24032414
problems.
@@ -2453,7 +2464,7 @@ Demonstration of how to create and use customized managers and proxies:
24532464
:language: python3
24542465

24552466

2456-
Using :class:`Pool`:
2467+
Using :class:`~multiprocessing.pool.Pool`:
24572468

24582469
.. literalinclude:: ../includes/mp_pool.py
24592470
:language: python3

‎Doc/library/queue.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,15 @@ The :mod:`queue` module defines the following classes and exceptions:
5454

5555
.. exception:: Empty
5656

57-
Exception raised when non-blocking :meth:`get` (or :meth:`get_nowait`) is called
57+
Exception raised when non-blocking :meth:`~Queue.get` (or
58+
:meth:`~Queue.get_nowait`) is called
5859
on a :class:`Queue` object which is empty.
5960

6061

6162
.. exception:: Full
6263

63-
Exception raised when non-blocking :meth:`put` (or :meth:`put_nowait`) is called
64+
Exception raised when non-blocking :meth:`~Queue.put` (or
65+
:meth:`~Queue.put_nowait`) is called
6466
on a :class:`Queue` object which is full.
6567

6668

@@ -181,6 +183,6 @@ Example of how to wait for enqueued tasks to be completed::
181183
context.
182184

183185
:class:`collections.deque` is an alternative implementation of unbounded
184-
queues with fast atomic :func:`append` and :func:`popleft` operations that
185-
do not require locking.
186+
queues with fast atomic :meth:`~collections.deque.append` and
187+
:meth:`~collections.deque.popleft` operations that do not require locking.
186188

0 commit comments

Comments
 (0)