[asyncio] Document loop.add_signal_handler

[hniksic]

BPO	35465
Nosy	@hniksic, @asvetlov, @1st1
PRs	bpo-35465: Document _UnixSelectorEventLoop.add_signal_handler. #11145 [3.7] bpo-35465: Document _UnixSelectorEventLoop.add_signal_handler. (GH-11145) #11221

^{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 2018-12-18.21:32:49.033>
created_at = <Date 2018-12-11.19:21:33.248>
labels = ['3.8', 'type-feature', '3.7', 'docs', 'expert-asyncio']
title = '[asyncio] Document loop.add_signal_handler'
updated_at = <Date 2018-12-18.21:52:40.664>
user = 'https://github.com/hniksic'

bugs.python.org fields:

activity = <Date 2018-12-18.21:52:40.664>
actor = 'yselivanov'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-12-18.21:32:49.033>
closer = 'yselivanov'
components = ['Documentation', 'asyncio']
creation = <Date 2018-12-11.19:21:33.248>
creator = 'hniksic'
dependencies = []
files = []
hgrepos = []
issue_num = 35465
keywords = ['patch']
message_count = 5.0
messages = ['331645', '331708', '331767', '332081', '332085']
nosy_count = 4.0
nosy_names = ['hniksic', 'asvetlov', 'docs@python', 'yselivanov']
pr_nums = ['11145', '11221']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35465'
versions = ['Python 3.7', 'Python 3.8']

[hniksic]

In https://stackoverflow.com/q/53704709/1600898 a StackOverflow user asked how the add_signal_handler event loop method differs from the signal.signal normally used by Python code.

The add_signal_handler documentation is quite brief - if we exclude the parts that explain the exceptions raised and how to pass keyword arguments to the callback, the meat is this sentence:

Set callback as the handler for the signum signal.

It is only after looking at the source, and understanding asyncio, that one comes to the conclusion that the idea is to run the handler along with other event loop callbacks and coroutines, at the time when it is actually safe to invoke asyncio code.

I think this deserves to be mentioned explicitly, for example:

Set callback as the handler for the signum signal.

The callback will be invoked in the thread that runs the event
loop, along with other queued callbacks and runnable coroutines.
Unlike signal handlers registered using signal.signal(), a 
callback registered with this function is allowed to interact
with the event loop.

[asvetlov]

The proposal sounds great!
Would you prepare a pull request for docs update?

[hniksic]

Done, #11145

[1st1]

New changeset e3666fc by Yury Selivanov (Hrvoje Nikšić) in branch 'master':
bpo-35465: Document _UnixSelectorEventLoop.add_signal_handler. (GH-11145)
e3666fc

[1st1]

New changeset 12f3979 by Yury Selivanov (Miss Islington (bot)) in branch '3.7':
bpo-35465: Document _UnixSelectorEventLoop.add_signal_handler. (GH-11145) (GH-11221)
12f3979