Add a note to QueueListener documentation saying that SimpleQueue instances can't be used in multiprocessing scenarios

[iamdbychkov]

BPO	46121
Nosy	@iamdbychkov

^{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 = None
created_at = <Date 2021-12-18.09:07:00.419>
labels = ['3.11', 'type-feature', '3.10', 'docs']
title = "Add a note to QueueListener documentation saying that SimpleQueue instances can't be used in multiprocessing scenarios"
updated_at = <Date 2021-12-18.09:07:00.419>
user = 'https://github.com/iamdbychkov'

bugs.python.org fields:

activity = <Date 2021-12-18.09:07:00.419>
actor = 'iamdbychkov'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-12-18.09:07:00.419>
creator = 'iamdbychkov'
dependencies = []
files = []
hgrepos = []
issue_num = 46121
keywords = []
message_count = 1.0
messages = ['408838']
nosy_count = 2.0
nosy_names = ['docs@python', 'iamdbychkov']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue46121'
versions = ['Python 3.10', 'Python 3.11']

[iamdbychkov]

Currently, documentation for QueueListener (https://docs.python.org/3/library/logging.handlers.html#queuelistener) says:
"""
supports receiving logging messages from a queue, such as those implemented in the queue or multiprocessing modules.
"""

While also saying that we can use queue.SimpleQueue as an underlying queue:

"""
The queue is not required to have the task tracking API, which means that you can use queue.SimpleQueue instances for queue.
"""

I think it should also say that neither queue.SimpleQueue nor multiprocessing.SimpleQueue instances will work if your intended use of QueueListener is to receive logging messages from processes spawned by multiprocessing module. One should use multiprocessing.Queue instance.

usage of queue.SimpleQueue will result in pickle exception.
multiprocessing.SimpleQueue lacks the API QueueListener expects from queue.

English is not my first language so I'll step aside from PR's in documentation :)