multiprocessing.Queue documentation is lacking important details

[GarrettMoore]

BPO	14206

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-07-02.12:04:18.456>
created_at = <Date 2012-03-06.00:32:41.560>
labels = ['docs']
title = 'multiprocessing.Queue documentation is lacking important details'
updated_at = <Date 2013-07-02.12:04:18.455>
user = 'https://bugs.python.org/GarrettMoore'

bugs.python.org fields:

activity = <Date 2013-07-02.12:04:18.455>
actor = 'sbt'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-07-02.12:04:18.456>
closer = 'sbt'
components = ['Documentation']
creation = <Date 2012-03-06.00:32:41.560>
creator = 'Garrett.Moore'
dependencies = []
files = []
hgrepos = []
issue_num = 14206
keywords = []
message_count = 3.0
messages = ['154995', '155011', '192188']
nosy_count = 4.0
nosy_names = ['docs@python', 'python-dev', 'sbt', 'Garrett.Moore']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue14206'
versions = ['Python 2.6', 'Python 2.7']

[GarrettMoore]

1. If cancel_join_thread() is called, data may be lost. This is not explicitly stated. I had multiple writers put() data in a Queue, and wanted to have the workers finish before I began consuming the data. This caused a deadlock because my Queue was not empty, and it seemed like the a way to force my workers finish was to use cancel_join_thread(). This caused data loss.

2. multiprocessing.Queue states "The Queue class is a near clone of Queue.Queue."

Queue.Queue states "If maxsize is less than or equal to zero, the queue size is infinite."

mp.Queue provides no information on queue size. It is reasonable to assume then that it inherits the property of Queue.Queue.

After discussion on IRC, it seems that mp.Queue maximum size is implementation-dependent and likely relies on how much data Pipes can hold on your platform. If this is the case there should be some mention of the fact that mp.Queue does NOT function like Queue.Queue does for maximum size.

[sbt]

What you were told on IRC was wrong. By default the queue *does* have infinite size.

When a process puts an item on the queue for the first time, a background thread is started which is responsible for writing items to the underlying pipe. This does mean that, on exit, the process should wait for the background thread to flush all the data to the pipe. This happens automatically unless you specifically prevent it by calling cancel_join_thread() method.

If you stick to those methods supported by standard queue objects, then things should work correctly.

(Maybe cancel_join_thread() would be better named allow_exit_without_flush().)

[python-dev]

New changeset f35401dba89f by Richard Oudkerk in branch '2.7':
Issue bpo-14206: Clarify docs for Queue.join_cancel_thread().
http://hg.python.org/cpython/rev/f35401dba89f

New changeset 9746f217a270 by Richard Oudkerk in branch '3.3':
Issue bpo-14206: Clarify docs for Queue.join_cancel_thread().
http://hg.python.org/cpython/rev/9746f217a270

New changeset d0b48efac9de by Richard Oudkerk in branch 'default':
Issue bpo-14206: Clarify docs for Queue.join_cancel_thread().
http://hg.python.org/cpython/rev/d0b48efac9de