BaseServer.shutdown documentation is incomplete

[ggenellina]

BPO	6031
Nosy	@birkenfeld, @bitdancer, @sandrotosi
Files	socketserver.rst.diff issue6031-py3k-v2.patch

^{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 2012-01-03.21:50:03.029>
created_at = <Date 2009-05-15.23:57:55.777>
labels = ['type-bug', 'docs']
title = 'BaseServer.shutdown documentation is incomplete'
updated_at = <Date 2012-01-03.21:50:03.026>
user = 'https://bugs.python.org/ggenellina'

bugs.python.org fields:

activity = <Date 2012-01-03.21:50:03.026>
actor = 'sandro.tosi'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-01-03.21:50:03.029>
closer = 'sandro.tosi'
components = ['Documentation']
creation = <Date 2009-05-15.23:57:55.777>
creator = 'ggenellina'
dependencies = []
files = ['15342', '19022']
hgrepos = []
issue_num = 6031
keywords = ['patch']
message_count = 6.0
messages = ['87845', '95286', '117407', '117557', '150537', '150538']
nosy_count = 5.0
nosy_names = ['georg.brandl', 'ggenellina', 'r.david.murray', 'sandro.tosi', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6031'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

[ggenellina]

BaseServer.shutdown is documented as "Tells the serve_forever() loop to
stop and waits until it does."

The docstring is much more explicit: """Stops the serve_forever loop.
Blocks until the loop has finished. This must be called while
serve_forever() is running in another thread, or it will deadlock."""

Combined with bpo-2302 I'd rewrite both (rst and docstring) as:

BaseServer.shutdown(): Tells the serve_forever() loop to stop, and
waits until the loop has finished. This must be called after
serve_forever() has started and while it is running in another thread,
or the shutdown() call will deadlock."

[ggenellina]

Documentation patch for BaseServer.server_forever() and shutdown()

[sandrotosi]

Hello,
I've refreshed this patch (correct the file name & because it applies now with an offset), other than that it seems ok: can someone review (it's quite small :) and apply it?

Thanks,
Sandro

[bitdancer]

Hmm. It seems as though since bpo-2302 is now closed, the comment about deadlocking if called before serve_forever may no longer be true. Gabriel?

[python-dev]

New changeset 4fad6b811c8b by Sandro Tosi in branch '2.7':
Issue bpo-6031: improve serve_forever() description
http://hg.python.org/cpython/rev/4fad6b811c8b

New changeset 4a30d36a9c69 by Sandro Tosi in branch '3.2':
Issue bpo-6031: improve serve_forever() description
http://hg.python.org/cpython/rev/4a30d36a9c69

[sandrotosi]

yep indeed, I've removed the deadlock part and committed.