Merge pull request jupyter-server#324 from mwakaba2/async-contents-api

Asynchronous Contents API

docs/source/developers/contents.rst

@@ -192,19 +192,19 @@ methods:
    ContentsManager.is_hidden
 
 You may be required to specify a Checkpoints object, as the default one,
-``FileCheckpoints``, could be incompatible with your custom 
+``FileCheckpoints``, could be incompatible with your custom
 ContentsManager.
 
 Customizing Checkpoints
 -----------------------
 .. currentmodule:: jupyter_server.services.contents.checkpoints
 
-Customized Checkpoint definitions allows behavior to be 
+Customized Checkpoint definitions allows behavior to be
 altered and extended.
 
 The ``Checkpoints`` and ``GenericCheckpointsMixin`` classes
 (from :mod:`jupyter_server.services.contents.checkpoints`)
-have reusable code and are intended to be used together, 
+have reusable code and are intended to be used together,
 but require the following methods to be implemented.
 
 .. autosummary::
@@ -220,7 +220,7 @@ No-op example
 ~~~~~~~~~~~~~
 
 Here is an example of a no-op checkpoints object - note the mixin
-comes first. The docstrings indicate what each method should do or 
+comes first. The docstrings indicate what each method should do or
 return for a more complete implementation.
 
 .. code-block:: python
@@ -238,7 +238,7 @@ return for a more complete implementation.
         def delete_checkpoint(self, checkpoint_id, path):
             """deletes a checkpoint for a file"""
         def list_checkpoints(self, path):
-            """returns a list of checkpoint models for a given file, 
+            """returns a list of checkpoint models for a given file,
             default just does one per file
             """
             return []
@@ -267,3 +267,24 @@ ContentsManager.
 .. _NBFormat: https://nbformat.readthedocs.io/en/latest/index.html
 .. _PGContents: https://github.com/quantopian/pgcontents
 .. _PostgreSQL: https://www.postgresql.org/
+
+Asynchronous Support
+--------------------
+
+An asynchronous version of the Contents API is available to run slow IO processes concurrently.
+
+- :class:`~manager.AsyncContentsManager`
+- :class:`~filemanager.AsyncFileContentsManager`
+- :class:`~largefilemanager.AsyncLargeFileManager`
+- :class:`~checkpoints.AsyncCheckpoints`
+- :class:`~checkpoints.AsyncGenericCheckpointsMixin`
+
+.. note::
+
+   .. _contentfree:
+
+   In most cases, the non-asynchronous Contents API is performant for local filesystems.
+   However, if the Jupyter Notebook web application is interacting with a high-latent virtual filesystem, you may see performance gains by using the asynchronous version.
+   For example, if you're experiencing terminal lag in the web application due to the slow and blocking file operations, the asynchronous version can reduce the lag.
+   Before opting in, comparing both non-async and async options' performances is recommended.
+