[Python-checkins] peps: Specify signal handling API.

[guido.van.rossum]

http://hg.python.org/peps/rev/a77060a3664e
changeset:   4659:a77060a3664e
user:        Guido van Rossum <guido at python.org>
date:        Tue Jan 08 11:21:53 2013 -0800
summary:
  Specify signal handling API.

files:
  pep-3156.txt |  30 ++++++++++++++++++++----------
  1 files changed, 20 insertions(+), 10 deletions(-)


diff --git a/pep-3156.txt b/pep-3156.txt
--- a/pep-3156.txt
+++ b/pep-3156.txt
@@ -223,9 +223,28 @@
   ``call_soon(callback, *args)``, but when called from another thread
   while the event loop is blocked waiting for I/O, unblocks the event
   loop.  This is the *only* method that is safe to call from another
-  thread or from a signal handler.  (To schedule a callback for a
+  thread.  (To schedule a callback for a
   later time in a threadsafe manner, you can use
   ``ev.call_soon_threadsafe(ev.call_later, when, callback, *args)``.)
+  This is not safe to call from a signal handler (since it may use
+  locks).
+
+- ``add_signal_handler(sig, callback, *args).  Whenever signal ``sig``
+  is received, arrange for ``callback(*args)`` to be called.  Returns
+  a ``Handler`` which can be used to cancel the signal callback.
+  Specifying another callback for the same signal replaces the
+  previous handler (only one handler can be active per signal).  The
+  ``sig`` must be a valid sigal number defined in the ``signal``
+  module.  If the signal cannot be handled this raises an exception:
+  ValueError if it is not a valid signal or if it is an uncatchable
+  signale (e.g. ``SIGKILL``), RuntimeError if this particular event
+  loop instance cannot handle signals (since signals are global per
+  process, only an event loop associated with the main thread can
+  handle signals).
+
+- ``remove_signal_handler(sig)``.  Removes the handler for signal
+  ``sig``, if one is set.  Raises the same exceptions as
+  ``add_signal_handler()``.
 
 - TBD: A way to register a callback that is already wrapped in a
   ``Handler``.  Maybe ``call_soon()`` could just check
@@ -900,15 +919,6 @@
   Finally, do we need support for unconnected datagram protocols?
   (That would mean wrappers for ``sendto()`` and ``recvfrom()``.)
 
-- Signal handling.  This is pretty UNIX-specific, but sometimes an
-  application needs to intercept signals.  It may be handy to have a
-  standard interface for this in the event loop, so everyone doesn't
-  have to reinvent this same wheel (with the same bugs).  It's
-  possible that this can be a thin wrapper on top of
-  ``call_soon_threadsafe()`` (assuming its implementation doesn't use
-  locks -- if it does, something different is needed, since a signal
-  handler may run while the thread is already holding a lock).
-
 - We may need APIs to control various timeouts.  E.g. we may want to
   limit the time spent in DNS resolution, connecting, ssl handshake,
   idle connection, close/shutdown, even per session.  Possibly it's

-- 
Repository URL: http://hg.python.org/peps