Merge pull request #5764 from takluyver/parallel-kernel-shutdown

Shut down kernels in parallel

IPython/kernel/manager.py

@@ -1,413 +1,420 b''
 """Base class to manage a running kernel"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import absolute_import
 
 # Standard library imports
 import os
 import re
 import signal
 import sys
 import time
 import warnings
 
 import zmq
 
 # Local imports
 from IPython.config.configurable import LoggingConfigurable
 from IPython.utils.importstring import import_item
 from IPython.utils.localinterfaces import is_local_ip, local_ips
 from IPython.utils.path import get_ipython_dir
 from IPython.utils.traitlets import (
     Any, Instance, Unicode, List, Bool, Type, DottedObjectName
 )
 from IPython.kernel import (
     make_ipkernel_cmd,
     launch_kernel,
     kernelspec,
 )
 from .connect import ConnectionFileMixin
 from .zmq.session import Session
 from .managerabc import (
     KernelManagerABC
 )
 
 
 class KernelManager(LoggingConfigurable, ConnectionFileMixin):
     """Manages a single kernel in a subprocess on this host.
 
     This version starts kernels with Popen.
     """
 
     # The PyZMQ Context to use for communication with the kernel.
     context = Instance(zmq.Context)
     def _context_default(self):
         return zmq.Context.instance()
 
     # The Session to use for communication with the kernel.
     session = Instance(Session)
     def _session_default(self):
         return Session(parent=self)
 
     # the class to create with our `client` method
     client_class = DottedObjectName('IPython.kernel.blocking.BlockingKernelClient')
     client_factory = Type()
     def _client_class_changed(self, name, old, new):
         self.client_factory = import_item(str(new))
 
     # The kernel process with which the KernelManager is communicating.
     # generally a Popen instance
     kernel = Any()
     
     kernel_spec_manager = Instance(kernelspec.KernelSpecManager)
     
     def _kernel_spec_manager_default(self):
         return kernelspec.KernelSpecManager(ipython_dir=self.ipython_dir)
     
     kernel_name = Unicode('python')
     
     kernel_spec = Instance(kernelspec.KernelSpec)
     
     def _kernel_spec_default(self):
         return self.kernel_spec_manager.get_kernel_spec(self.kernel_name)
     
     def _kernel_name_changed(self, name, old, new):
         self.kernel_spec = self.kernel_spec_manager.get_kernel_spec(new)
         self.ipython_kernel = new in {'python', 'python2', 'python3'}
 
     kernel_cmd = List(Unicode, config=True,
         help="""DEPRECATED: Use kernel_name instead.
         
         The Popen Command to launch the kernel.
         Override this if you have a custom kernel.
         If kernel_cmd is specified in a configuration file,
         IPython does not pass any arguments to the kernel,
         because it cannot make any assumptions about the 
         arguments that the kernel understands. In particular,
         this means that the kernel does not receive the
         option --debug if it given on the IPython command line.
         """
     )
 
     def _kernel_cmd_changed(self, name, old, new):
         warnings.warn("Setting kernel_cmd is deprecated, use kernel_spec to "
                       "start different kernels.")
         self.ipython_kernel = False
 
     ipython_kernel = Bool(True)
     
     ipython_dir = Unicode()
     def _ipython_dir_default(self):
         return get_ipython_dir()
 
     # Protected traits
     _launch_args = Any()
     _control_socket = Any()
 
     _restarter = Any()
 
     autorestart = Bool(False, config=True,
         help="""Should we autorestart the kernel if it dies."""
     )
 
     def __del__(self):
         self._close_control_socket()
         self.cleanup_connection_file()
 
     #--------------------------------------------------------------------------
     # Kernel restarter
     #--------------------------------------------------------------------------
 
     def start_restarter(self):
         pass
 
     def stop_restarter(self):
         pass
 
     def add_restart_callback(self, callback, event='restart'):
         """register a callback to be called when a kernel is restarted"""
         if self._restarter is None:
             return
         self._restarter.add_callback(callback, event)
 
     def remove_restart_callback(self, callback, event='restart'):
         """unregister a callback to be called when a kernel is restarted"""
         if self._restarter is None:
             return
         self._restarter.remove_callback(callback, event)
 
     #--------------------------------------------------------------------------
     # create a Client connected to our Kernel
     #--------------------------------------------------------------------------
 
     def client(self, **kwargs):
         """Create a client configured to connect to our kernel"""
         if self.client_factory is None:
             self.client_factory = import_item(self.client_class)
 
         kw = {}
         kw.update(self.get_connection_info())
         kw.update(dict(
             connection_file=self.connection_file,
             session=self.session,
             parent=self,
         ))
 
         # add kwargs last, for manual overrides
         kw.update(kwargs)
         return self.client_factory(**kw)
 
     #--------------------------------------------------------------------------
     # Kernel management
     #--------------------------------------------------------------------------
 
     def format_kernel_cmd(self, **kw):
         """replace templated args (e.g. {connection_file})"""
         if self.kernel_cmd:
             cmd = self.kernel_cmd
         elif self.kernel_name == 'python':
             # The native kernel gets special handling
             cmd = make_ipkernel_cmd(
                 'from IPython.kernel.zmq.kernelapp import main; main()',
                 **kw
             )
         else:
             cmd = self.kernel_spec.argv
 
         ns = dict(connection_file=self.connection_file)
         ns.update(self._launch_args)
         
         pat = re.compile(r'\{([A-Za-z0-9_]+)\}')
         def from_ns(match):
             """Get the key out of ns if it's there, otherwise no change."""
             return ns.get(match.group(1), match.group())
         
         return [ pat.sub(from_ns, arg) for arg in cmd ]
 
     def _launch_kernel(self, kernel_cmd, **kw):
         """actually launch the kernel
 
         override in a subclass to launch kernel subprocesses differently
         """
         return launch_kernel(kernel_cmd, **kw)
 
     # Control socket used for polite kernel shutdown
 
     def _connect_control_socket(self):
         if self._control_socket is None:
             self._control_socket = self.connect_control()
             self._control_socket.linger = 100
 
     def _close_control_socket(self):
         if self._control_socket is None:
             return
         self._control_socket.close()
         self._control_socket = None
 
     def start_kernel(self, **kw):
         """Starts a kernel on this host in a separate process.
 
         If random ports (port=0) are being used, this method must be called
         before the channels are created.
 
         Parameters
         ----------
         **kw : optional
              keyword arguments that are passed down to build the kernel_cmd
              and launching the kernel (e.g. Popen kwargs).
         """
         if self.transport == 'tcp' and not is_local_ip(self.ip):
             raise RuntimeError("Can only launch a kernel on a local interface. "
                                "Make sure that the '*_address' attributes are "
                                "configured properly. "
                                "Currently valid addresses are: %s" % local_ips()
                                )
 
         # write connection file / get default ports
         self.write_connection_file()
 
         # save kwargs for use in restart
         self._launch_args = kw.copy()
         # build the Popen cmd
         kernel_cmd = self.format_kernel_cmd(**kw)
         if self.kernel_cmd:
             # If kernel_cmd has been set manually, don't refer to a kernel spec
             env = os.environ
         else:
             # Environment variables from kernel spec are added to os.environ
             env = os.environ.copy()
             env.update(self.kernel_spec.env or {})
         # launch the kernel subprocess
         self.kernel = self._launch_kernel(kernel_cmd, env=env,
                                     ipython_kernel=self.ipython_kernel,
                                     **kw)
         self.start_restarter()
         self._connect_control_socket()
 
-    def _send_shutdown_request(self, restart=False):
-        """TODO: send a shutdown request via control channel"""
+    def request_shutdown(self, restart=False):
+        """Send a shutdown request via control channel
+        
+        On Windows, this just kills kernels instead, because the shutdown
+        messages don't work.
+        """
         content = dict(restart=restart)
         msg = self.session.msg("shutdown_request", content=content)
         self.session.send(self._control_socket, msg)
 
+    def finish_shutdown(self, waittime=1, pollinterval=0.1):
+        """Wait for kernel shutdown, then kill process if it doesn't shutdown.
+        
+        This does not send shutdown requests - use :meth:`request_shutdown`
+        first.
+        """
+        for i in range(int(waittime/pollinterval)):
+            if self.is_alive():
+                time.sleep(pollinterval)
+            else:
+                break
+        else:
+            # OK, we've waited long enough.
+            if self.has_kernel:
+                self._kill_kernel()
+
+    def cleanup(self, connection_file=True):
+        """Clean up resources when the kernel is shut down"""
+        if connection_file:
+            self.cleanup_connection_file()
+
+        self.cleanup_ipc_files()
+        self._close_control_socket()
+
     def shutdown_kernel(self, now=False, restart=False):
         """Attempts to the stop the kernel process cleanly.
 
         This attempts to shutdown the kernels cleanly by:
 
         1. Sending it a shutdown message over the shell channel.
         2. If that fails, the kernel is shutdown forcibly by sending it
            a signal.
 
         Parameters
         ----------
         now : bool
             Should the kernel be forcible killed *now*. This skips the
             first, nice shutdown attempt.
         restart: bool
             Will this kernel be restarted after it is shutdown. When this
             is True, connection files will not be cleaned up.
         """
         # Stop monitoring for restarting while we shutdown.
         self.stop_restarter()
 
-        # FIXME: Shutdown does not work on Windows due to ZMQ errors!
-        if now or sys.platform == 'win32':
-            if self.has_kernel:
-                self._kill_kernel()
+        if now:
+            self._kill_kernel()
         else:
+            self.request_shutdown(restart=restart)
             # Don't send any additional kernel kill messages immediately, to give
             # the kernel a chance to properly execute shutdown actions. Wait for at
             # most 1s, checking every 0.1s.
-            self._send_shutdown_request(restart=restart)
-            for i in range(10):
-                if self.is_alive():
-                    time.sleep(0.1)
-                else:
-                    break
-            else:
-                # OK, we've waited long enough.
-                if self.has_kernel:
-                    self._kill_kernel()
+            self.finish_shutdown()
 
-        if not restart:
-            self.cleanup_connection_file()
-            self.cleanup_ipc_files()
-        else:
-            self.cleanup_ipc_files()
-        
-        self._close_control_socket()
+        self.cleanup(connection_file=not restart)
 
     def restart_kernel(self, now=False, **kw):
         """Restarts a kernel with the arguments that were used to launch it.
 
         If the old kernel was launched with random ports, the same ports will be
         used for the new kernel. The same connection file is used again.
 
         Parameters
         ----------
         now : bool, optional
             If True, the kernel is forcefully restarted *immediately*, without
             having a chance to do any cleanup action.  Otherwise the kernel is
             given 1s to clean up before a forceful restart is issued.
 
             In all cases the kernel is restarted, the only difference is whether
             it is given a chance to perform a clean shutdown or not.
 
         **kw : optional
             Any options specified here will overwrite those used to launch the
             kernel.
         """
         if self._launch_args is None:
             raise RuntimeError("Cannot restart the kernel. "
                                "No previous call to 'start_kernel'.")
         else:
             # Stop currently running kernel.
             self.shutdown_kernel(now=now, restart=True)
 
             # Start new kernel.
             self._launch_args.update(kw)
             self.start_kernel(**self._launch_args)
 
-            # FIXME: Messages get dropped in Windows due to probable ZMQ bug
-            # unless there is some delay here.
-            if sys.platform == 'win32':
-                time.sleep(0.2)
-
     @property
     def has_kernel(self):
         """Has a kernel been started that we are managing."""
         return self.kernel is not None
 
     def _kill_kernel(self):
         """Kill the running kernel.
 
         This is a private method, callers should use shutdown_kernel(now=True).
         """
         if self.has_kernel:
 
             # Signal the kernel to terminate (sends SIGKILL on Unix and calls
             # TerminateProcess() on Win32).
             try:
                 self.kernel.kill()
             except OSError as e:
                 # In Windows, we will get an Access Denied error if the process
                 # has already terminated. Ignore it.
                 if sys.platform == 'win32':
                     if e.winerror != 5:
                         raise
                 # On Unix, we may get an ESRCH error if the process has already
                 # terminated. Ignore it.
                 else:
                     from errno import ESRCH
                     if e.errno != ESRCH:
                         raise
 
             # Block until the kernel terminates.
             self.kernel.wait()
             self.kernel = None
         else:
             raise RuntimeError("Cannot kill kernel. No kernel is running!")
 
     def interrupt_kernel(self):
         """Interrupts the kernel by sending it a signal.
 
         Unlike ``signal_kernel``, this operation is well supported on all
         platforms.
         """
         if self.has_kernel:
             if sys.platform == 'win32':
                 from .zmq.parentpoller import ParentPollerWindows as Poller
                 Poller.send_interrupt(self.kernel.win32_interrupt_event)
             else:
                 self.kernel.send_signal(signal.SIGINT)
         else:
             raise RuntimeError("Cannot interrupt kernel. No kernel is running!")
 
     def signal_kernel(self, signum):
         """Sends a signal to the kernel.
 
         Note that since only SIGTERM is supported on Windows, this function is
         only useful on Unix systems.
         """
         if self.has_kernel:
             self.kernel.send_signal(signum)
         else:
             raise RuntimeError("Cannot signal kernel. No kernel is running!")
 
     def is_alive(self):
         """Is the kernel process still running?"""
         if self.has_kernel:
             if self.kernel.poll() is None:
                 return True
             else:
                 return False
         else:
             # we don't have a kernel
             return False
 
 
 KernelManagerABC.register(KernelManager)
 

IPython/kernel/multikernelmanager.py

@@ -1,302 +1,322 b''
 """A kernel manager for multiple kernels
 
 Authors:
 
 * Brian Granger
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2013  The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 from __future__ import absolute_import
 
 import os
 import uuid
 
 import zmq
 
 from IPython.config.configurable import LoggingConfigurable
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import (
     Instance, Dict, Unicode, Any, DottedObjectName
 )
 from IPython.utils.py3compat import unicode_type
 
 #-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class DuplicateKernelError(Exception):
     pass
 
 
 
 def kernel_method(f):
     """decorator for proxying MKM.method(kernel_id) to individual KMs by ID"""
     def wrapped(self, kernel_id, *args, **kwargs):
         # get the kernel
         km = self.get_kernel(kernel_id)
         method = getattr(km, f.__name__)
         # call the kernel's method
         r = method(*args, **kwargs)
         # last thing, call anything defined in the actual class method
         # such as logging messages
         f(self, kernel_id, *args, **kwargs)
         # return the method result
         return r
     return wrapped
 
 
 class MultiKernelManager(LoggingConfigurable):
     """A class for managing multiple kernels."""
     
     kernel_manager_class = DottedObjectName(
         "IPython.kernel.ioloop.IOLoopKernelManager", config=True,
         help="""The kernel manager class.  This is configurable to allow
         subclassing of the KernelManager for customized behavior.
         """
     )
     def _kernel_manager_class_changed(self, name, old, new):
         self.kernel_manager_factory = import_item(new)
     
     kernel_manager_factory = Any(help="this is kernel_manager_class after import")
     def _kernel_manager_factory_default(self):
         return import_item(self.kernel_manager_class)
     
     context = Instance('zmq.Context')
     def _context_default(self):
         return zmq.Context.instance()
 
     connection_dir = Unicode('')
 
     _kernels = Dict()
 
     def list_kernel_ids(self):
         """Return a list of the kernel ids of the active kernels."""
         # Create a copy so we can iterate over kernels in operations
         # that delete keys.
         return list(self._kernels.keys())
 
     def __len__(self):
         """Return the number of running kernels."""
         return len(self.list_kernel_ids())
 
     def __contains__(self, kernel_id):
         return kernel_id in self._kernels
 
     def start_kernel(self, **kwargs):
         """Start a new kernel.
 
         The caller can pick a kernel_id by passing one in as a keyword arg,
         otherwise one will be picked using a uuid.
 
         To silence the kernel's stdout/stderr, call this using::
 
             km.start_kernel(stdout=PIPE, stderr=PIPE)
 
         """
         kernel_id = kwargs.pop('kernel_id', unicode_type(uuid.uuid4()))
         if kernel_id in self:
             raise DuplicateKernelError('Kernel already exists: %s' % kernel_id)
         # kernel_manager_factory is the constructor for the KernelManager
         # subclass we are using. It can be configured as any Configurable,
         # including things like its transport and ip.
         km = self.kernel_manager_factory(connection_file=os.path.join(
                     self.connection_dir, "kernel-%s.json" % kernel_id),
                     parent=self, autorestart=True, log=self.log
         )
         km.start_kernel(**kwargs)
         self._kernels[kernel_id] = km
         return kernel_id
 
     @kernel_method
-    def shutdown_kernel(self, kernel_id, now=False):
+    def shutdown_kernel(self, kernel_id, now=False, restart=False):
         """Shutdown a kernel by its kernel uuid.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel to shutdown.
         now : bool
             Should the kernel be shutdown forcibly using a signal.
+        restart : bool
+            Will the kernel be restarted?
         """
         self.log.info("Kernel shutdown: %s" % kernel_id)
         self.remove_kernel(kernel_id)
 
+    @kernel_method
+    def request_shutdown(self, kernel_id, restart=False):
+        """Ask a kernel to shut down by its kernel uuid"""
+
+    @kernel_method
+    def finish_shutdown(self, kernel_id, waittime=1, pollinterval=0.1):
+        """Wait for a kernel to finish shutting down, and kill it if it doesn't
+        """
+        self.log.info("Kernel shutdown: %s" % kernel_id)
+
+    @kernel_method
+    def cleanup(self, kernel_id, connection_file=True):
+        """Clean up a kernel's resources"""
+
     def remove_kernel(self, kernel_id):
         """remove a kernel from our mapping.
 
         Mainly so that a kernel can be removed if it is already dead,
         without having to call shutdown_kernel.
 
         The kernel object is returned.
         """
         return self._kernels.pop(kernel_id)
 
     def shutdown_all(self, now=False):
         """Shutdown all kernels."""
-        for kid in self.list_kernel_ids():
-            self.shutdown_kernel(kid, now=now)
+        kids = self.list_kernel_ids()
+        for kid in kids:
+            self.request_shutdown(kid)
+        for kid in kids:
+            self.finish_shutdown(kid)
+            self.cleanup(kid)
 
     @kernel_method
     def interrupt_kernel(self, kernel_id):
         """Interrupt (SIGINT) the kernel by its uuid.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel to interrupt.
         """
         self.log.info("Kernel interrupted: %s" % kernel_id)
 
     @kernel_method
     def signal_kernel(self, kernel_id, signum):
         """Sends a signal to the kernel by its uuid.
 
         Note that since only SIGTERM is supported on Windows, this function
         is only useful on Unix systems.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel to signal.
         """
         self.log.info("Signaled Kernel %s with %s" % (kernel_id, signum))
 
     @kernel_method
     def restart_kernel(self, kernel_id, now=False):
         """Restart a kernel by its uuid, keeping the same ports.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel to interrupt.
         """
         self.log.info("Kernel restarted: %s" % kernel_id)
 
     @kernel_method
     def is_alive(self, kernel_id):
         """Is the kernel alive.
 
         This calls KernelManager.is_alive() which calls Popen.poll on the
         actual kernel subprocess.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel.
         """
 
     def _check_kernel_id(self, kernel_id):
         """check that a kernel id is valid"""
         if kernel_id not in self:
             raise KeyError("Kernel with id not found: %s" % kernel_id)
 
     def get_kernel(self, kernel_id):
         """Get the single KernelManager object for a kernel by its uuid.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel.
         """
         self._check_kernel_id(kernel_id)
         return self._kernels[kernel_id]
 
     @kernel_method
     def add_restart_callback(self, kernel_id, callback, event='restart'):
         """add a callback for the KernelRestarter"""
 
     @kernel_method
     def remove_restart_callback(self, kernel_id, callback, event='restart'):
         """remove a callback for the KernelRestarter"""
 
     @kernel_method
     def get_connection_info(self, kernel_id):
         """Return a dictionary of connection data for a kernel.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel.
 
         Returns
         =======
         connection_dict : dict
             A dict of the information needed to connect to a kernel.
             This includes the ip address and the integer port
             numbers of the different channels (stdin_port, iopub_port,
             shell_port, hb_port).
         """
 
     @kernel_method
     def connect_iopub(self, kernel_id, identity=None):
         """Return a zmq Socket connected to the iopub channel.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel
         identity : bytes (optional)
             The zmq identity of the socket
 
         Returns
         =======
         stream : zmq Socket or ZMQStream
         """
 
     @kernel_method
     def connect_shell(self, kernel_id, identity=None):
         """Return a zmq Socket connected to the shell channel.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel
         identity : bytes (optional)
             The zmq identity of the socket
 
         Returns
         =======
         stream : zmq Socket or ZMQStream
         """
 
     @kernel_method
     def connect_stdin(self, kernel_id, identity=None):
         """Return a zmq Socket connected to the stdin channel.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel
         identity : bytes (optional)
             The zmq identity of the socket
 
         Returns
         =======
         stream : zmq Socket or ZMQStream
         """
 
     @kernel_method
     def connect_hb(self, kernel_id, identity=None):
         """Return a zmq Socket connected to the hb channel.
 
         Parameters
         ==========
         kernel_id : uuid
             The id of the kernel
         identity : bytes (optional)
             The zmq identity of the socket
 
         Returns
         =======
         stream : zmq Socket or ZMQStream
         """