add docs for pending kernels

docs/index.rst

@@ -24,6 +24,7 @@ with Jupyter kernels.
    kernels
    wrapperkernels
    provisioning
+   pending-kernels
 
 .. toctree::
    :maxdepth: 2

docs/pending-kernels.rst

@@ -0,0 +1,36 @@
+Pending Kernels
+===============
+
+*Added in 7.1.0*
+
+In scenarios where an kernel takes a long time to start (e.g. kernels running remotely), it can be advantageous to immediately return the kernel's model and ID from key methods like ``.start_kernel()`` and ``.shutdown_kernel()``. The kernel will continue its task without blocking other managerial actions.
+
+This intermediate state is called a **"pending kernel"**.
+
+How they work
+-------------
+
+When ``.start_kernel()`` or ``.shutdown_kernel()`` is called, a ``Future`` is created under the ``KernelManager.ready`` property. This property can be awaited anytime to ensure that the kernel moves out of its pending state, e.g.:
+
+.. code-block:: python
+
+    # await a Kernel Manager's `.ready` property to
+    # block further action until the kernel is out
+    # of its pending state.
+    await kernel_manager.ready
+
+Once the kernel is finished pending, ``.ready.done()`` will be ``True`` and either 1) ``.ready.result()`` will return ``None`` or 2) ``.ready.exception()`` will return a raised exception
+
+Using pending kernels
+---------------------
+
+The most common way to interact with pending kernels is through the ``MultiKernelManager``—the object that manages a collection of kernels—by setting its ``use_pending_kernels`` trait to ``True``. Pending kernels are "opt-in"; they are not used by default in the ``MultiKernelManager``.
+
+When ``use_pending_kernels`` is ``True``, the following changes are made to the ``MultiKernelManager``:
+
+1. ``start_kernel`` and ``stop_kernel`` return immediately while running the pending task in a background thread.
+2. The following methods raise a ``RuntimeError`` if a kernel is pending:
+    * ``restart_kernel``
+    * ``interrupt_kernel``
+    * ``shutdown_kernel``
+3. ``shutdown_all`` will wait for all pending kernels to become ready before attempting to shut them down.