https://github.com/python/cpython/commit/1f06ef793e0a23ab119ab24f468e3408b89bdc30 commit: 1f06ef793e0a23ab119ab24f468e3408b89bdc30 branch: 3.14 author: An Long <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-10-12T21:23:24-04:00 summary:
[3.14] gh-136563: Update `concurrent.interpreters` module documentation (GH-139358) (GH-159282) (cherry picked from commit fd671619e7054706fd62c187749c806f18f068e1) Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/concurrent.interpreters.rst diff --git a/Doc/library/concurrent.interpreters.rst b/Doc/library/concurrent.interpreters.rst index 31b964b8317fdb..fee2d6ba634c23 100644 --- a/Doc/library/concurrent.interpreters.rst +++ b/Doc/library/concurrent.interpreters.rst @@ -227,11 +227,15 @@ This module defines the following functions: Initialize a new (idle) Python interpreter and return a :class:`Interpreter` object for it. -.. function:: create_queue() +.. function:: create_queue(maxsize=0) Initialize a new cross-interpreter queue and return a :class:`Queue` object for it. + *maxsize* is an integer that sets the upperbound limit on the number of + items that can be placed in the queue. Insertion will be blocked once this + size has been reached, until queue items are consumed. If *maxsize* is + less than or equal to zero, the queue size is infinite. Interpreter objects ^^^^^^^^^^^^^^^^^^^ @@ -271,7 +275,7 @@ Interpreter objects Some objects are actually shared and some are copied efficiently, but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`. - .. method:: exec(code, /, dedent=True) + .. method:: exec(code, /) Run the given source code in the interpreter (in the current thread). @@ -322,7 +326,9 @@ Communicating Between Interpreters .. class:: Queue(id) A wrapper around a low-level, cross-interpreter queue, which - implements the :class:`queue.Queue` interface. The underlying queue + implements all the methods of :class:`queue.Queue` except for + :meth:`~queue.Queue.task_done`, :meth:`~queue.Queue.join` + and :meth:`~queue.Queue.shutdown`. The underlying queue can only be created through :func:`create_queue`. Some objects are actually shared and some are copied efficiently, @@ -334,17 +340,59 @@ Communicating Between Interpreters The queue's ID. + .. method:: qsize() -.. exception:: QueueEmptyError + Return the number of items in the queue. + + .. method:: empty() + + Return ``True`` if the queue is empty, ``False`` otherwise. + + .. method:: full() + + Return ``True`` if the queue is full, ``False`` otherwise. + + .. method:: put(obj, block=True, timeout=None) + + Put *obj* into the queue. If optional args *block* is true and + *timeout* is ``None`` (the default), block if necessary until a free + slot is available. If *timeout* is a positive number, it blocks at + most *timeout* seconds and raises the :exc:`QueueFull` exception if + no free slot was available within that time. Otherwise (*block* is + false), put an object on the queue if a free slot is immediately + available, else raise the :exc:`QueueFull` exception (*timeout* is + ignored in that case). + + .. method:: put_nowait(obj) + + Equivalent to ``put(obj, block=False)``. + + .. method:: get(block=True, timeout=None) + + Remove and return an object from the queue. If optional args *block* + is true and *timeout* is ``None`` (the default), block if necessary + until an object is available. If *timeout* is a positive number, it + blocks at most *timeout* seconds and raises the :exc:`QueueEmpty` + exception if no object was available within that time. Otherwise + (*block* is false), return an object if one is immediately available, + else raise the :exc:`QueueEmpty` exception (*timeout* is ignored in + that case). + + .. method:: get_nowait() + + Equivalent to ``get(block=False)``. + + +.. exception:: QueueEmpty This exception, a subclass of :exc:`queue.Empty`, is raised from - :meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the queue + :meth:`Queue.get` and :meth:`Queue.get_nowait` when the queue is empty. -.. exception:: QueueFullError +.. exception:: QueueFull This exception, a subclass of :exc:`queue.Full`, is raised from - :meth:`!Queue.put` and :meth:`!Queue.put_nowait` when the queue + :meth:`Queue.put` and :meth:`Queue.put_nowait` when the queue is full. @@ -385,3 +433,17 @@ Creating an interpreter and running code in it:: t = interp.call_in_thread(run) t.join() + +Communicating between interpreters with a queue:: + + from concurrent import interpreters + + interp = interpreters.create() + queue = interpreters.create_queue() + + def worker(queue): + queue.put('spam!') + + t = interp.call_in_thread(worker, queue) + print(queue.get()) + t.join() _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
