Use asyncio

boot.py

@@ -17,6 +17,7 @@
 from .plugin.configuration import LspDisableLanguageServerInProjectCommand
 from .plugin.configuration import LspEnableLanguageServerGloballyCommand
 from .plugin.configuration import LspEnableLanguageServerInProjectCommand
+from .plugin.core.aio import run_coroutine
 from .plugin.core.constants import ST_VERSION
 from .plugin.core.css import load as load_css
 from .plugin.core.open import g_opening_files
@@ -90,10 +91,18 @@
 from .plugin.tooling import LspParseVscodePackageJson
 from .plugin.tooling import LspTroubleshootServerCommand
 from typing import Any
+from typing import TYPE_CHECKING
 import os
 import sublime
+import sublime_aio
 import sublime_plugin
 
+if TYPE_CHECKING:
+    import asyncio
+
+# Uncomment to see all invocations that are marked @deprecated in the Console.
+# warnings.simplefilter('always', DeprecationWarning)
+
 __all__ = (
     "DocumentSyncListener",
     "Listener",
@@ -222,18 +231,18 @@ def show_warning() -> None:
 
 def plugin_unloaded() -> None:
     _unregister_all_plugins()
-    windows.disable()
+    run_coroutine(windows.disable())
     for listeners in sublime_plugin.view_event_listeners.values():
         for listener in listeners:
             if isinstance(listener, DocumentSyncListener):
                 listener.before_destroy()
     unload_settings()
 
 
-class Listener(sublime_plugin.EventListener):
+class Listener(sublime_aio.EventListener):
 
-    def on_exit(self) -> None:
-        kill_all_subprocesses()
+    async def on_exit(self) -> None:
+        await kill_all_subprocesses()
 
     def on_load_project_async(self, window: sublime.Window) -> None:
         if manager := windows.lookup(window):
@@ -262,27 +271,26 @@ def on_pre_move(self, view: sublime.View) -> None:
                     sublime.set_timeout_async(listener.on_post_move_window_async, 1)
                     return
 
-    def on_load(self, view: sublime.View) -> None:
+    async def on_load(self, view: sublime.View) -> None:
         file_name = view.file_name()
         if not file_name:
             return
-        for fn in g_opening_files:
-            if fn == file_name or os.path.samefile(fn, file_name):
-                # Remove it from the pending opening files, and resolve the promise.
-                g_opening_files.pop(fn)[1](view)
-                break
+        if future := self._find_opening_file_future(file_name):
+            future.set_result(view)
 
-    def on_pre_close(self, view: sublime.View) -> None:
+    async def on_pre_close(self, view: sublime.View) -> None:
         file_name = view.file_name()
         if not file_name:
             return
+        if future := self._find_opening_file_future(file_name):
+            # The view got closed before it finished loading. This can happen.
+            future.set_result(None)
+
+    def _find_opening_file_future(self, file_name: str) -> asyncio.Future[sublime.View | None] | None:
         for fn in g_opening_files:
             if fn == file_name or os.path.samefile(fn, file_name):
-                tup = g_opening_files.pop(fn, None)  # noqa: B909
-                if tup:
-                    # The view got closed before it finished loading. This can happen.
-                    tup[1](None)
-                    break
+                return g_opening_files.pop(fn, None)
+        return None
 
     def on_post_window_command(self, window: sublime.Window, command_name: str, args: dict[str, Any] | None) -> None:
         if command_name == "show_panel":

dependencies.json

@@ -4,6 +4,7 @@
             "bracex",
             "mdpopups",
             "orjson",
+            "sublime_aio",
             "typing_extensions",
             "wcmatch"
         ]

plugin/__init__.py

@@ -11,6 +11,9 @@
 from .api import request_handler
 from .api import unregister_plugin
 from .api import uri_handler
+from .core.aio import run_coroutine
+from .core.aio import run_on_asyncio_thread
+from .core.aio import run_on_threadpool
 from .core.collections import DottedDict
 from .core.constants import MarkdownLangMap
 from .core.constants import ST_STORAGE_PATH
@@ -95,6 +98,9 @@
     'register_file_watcher_implementation',
     'register_plugin',
     'request_handler',
+    'run_coroutine',
+    'run_on_asyncio_thread',
+    'run_on_threadpool',
     'unregister_plugin',
     'uri_from_view',
     'uri_handler',

plugin/api.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 from ..protocol import LSPAny
+from .core.aio import run_on_threadpool
 from .core.constants import ST_STORAGE_PATH
 from .core.logging import exception_log
-from .core.promise import Promise
 from .core.protocol import Response
 from .core.settings import client_configs
 from .core.types import method2attr
@@ -15,6 +15,7 @@
 from functools import wraps
 from pathlib import Path
 from typing import Any
+from typing import Awaitable
 from typing import Callable
 from typing import Final
 from typing import final
@@ -54,14 +55,14 @@
 # P represents the parameters *after* the 'self' argument
 P = TypeVar('P', bound=LSPAny)
 R = TypeVar('R', bound=LSPAny)
-CommandHandler = Callable[['list[P] | None'], 'Promise[R]']
-CommandHandlerForDecorator = Callable[[Any, 'list[P] | None'], 'Promise[R]']
-UriHandler = Callable[['DocumentUri', sublime.NewFileFlags], 'Promise[sublime.Sheet | None]']
+CommandHandler = Callable[['list[P] | None'], 'Awaitable[R]']
+CommandHandlerForDecorator = Callable[[Any, 'list[P] | None'], 'Awaitable[R]']
+UriHandler = Callable[['DocumentUri', sublime.NewFileFlags], 'Awaitable[sublime.Sheet | None]']
 # Decorator needs a dedicated type with `Any` as the first parameter representing `Self` to make its
 # implementation happy. I couldn't find a better way (Concatenate and ParamSpec don't seem to help here).
-UriHandlerForDecorator = Callable[[Any, 'DocumentUri', sublime.NewFileFlags], 'Promise[sublime.Sheet | None]']
+UriHandlerForDecorator = Callable[[Any, 'DocumentUri', sublime.NewFileFlags], 'Awaitable[sublime.Sheet | None]']
 PostResponseCallback = Callable[[], None]
-RequestHandlerResponse = Union[Promise[R], Tuple[Promise[R], PostResponseCallback]]
+RequestHandlerResponse = Union[R, Tuple[R, PostResponseCallback]]
 
 
 g_plugins: dict[str, type[AbstractPlugin | LspPlugin]] = {}
@@ -225,36 +226,41 @@ def decorator(func: Callable[[Any, P], None]) -> Callable[[Any, P], None]:
 
 def request_handler(
     method: str
-) -> Callable[[Callable[[Any, P], RequestHandlerResponse]], Callable[[Any, P, int], Promise[Response[R]]]]:  # pyright: ignore[reportInvalidTypeVarUse]
+) -> Callable[[Callable[[Any, P], Awaitable[RequestHandlerResponse]]], Callable[[Any, P, int], Awaitable[Response[R]]]]:  # pyright: ignore[reportInvalidTypeVarUse]
     """
-    Decorator to mark a method as a handler for a specific LSP request.
+    Decorator to mark a coroutine method as a handler for a specific LSP request.
 
     Usage:
         ```py
         @request_handler('eslint/openDoc')
-        def on_open_doc(self, params: TextDocumentIdentifier) -> Promise[bool]:
+        async def on_open_doc(self, params: TextDocumentIdentifier) -> bool:
             ...
         ```
 
-    The decorated method will be called with the request parameters whenever the specified
-    request is received from the language server. The method must return a Promise that resolves
-    to the response value. The framework will automatically send it back to the server.
+    The decorated coroutine method will be called with the request parameters whenever the specified
+    request is received from the language server. The coroutine method must return a response value.
+    The framework will automatically send it back to the server.
+
+    An older, but backwards-compatible way to define a request handler is by defining a function that returns a Promise.
+    While that works, the advice is to define a coroutine function.
 
     :param      method:             The LSP request method name (e.g., 'eslint/openDoc').
-    :returns:   A decorator that registers the function as a request handler.
+    :returns:   A decorator that registers the coroutine function as a request handler.
     """
 
-    def decorator(func: Callable[[Any, P], RequestHandlerResponse]) -> Callable[[Any, P, int], Promise[Response[R]]]:
+    def decorator(
+        func: Callable[[Any, P], Awaitable[RequestHandlerResponse]]
+    ) -> Callable[[Any, P, int], Awaitable[Response[R]]]:
 
         @wraps(func)
-        def wrapper(self: Any, params: P, request_id: int) -> Promise[Response[Any]]:
-            promise_or_tuple = func(self, params)
-            if isinstance(promise_or_tuple, tuple):
-                promise, post_request_callback = promise_or_tuple
+        async def wrapper(self: Any, params: P, request_id: int) -> Response[Any]:
+            response = await func(self, params)
+            if isinstance(response, tuple):
+                result, post_request_callback = response
             else:
-                promise = promise_or_tuple
+                result = response
                 post_request_callback = None
-            return promise.then(lambda result: Response(request_id, result, post_request_callback))
+            return Response(request_id, result, post_request_callback)
 
         setattr(wrapper, HANDLER_MARKER, method)
         return wrapper
@@ -272,7 +278,7 @@ def command_handler(command_name: str) -> Callable[[CommandHandlerForDecorator],
     Usage:
         ```py
         @command_handler('typescript.rename')
-        def on_custom_rename(self, arguments: list[LSPAny] | None) -> Promise[LspAny]:
+        async def on_custom_rename(self, arguments: list[LSPAny] | None) -> LspAny:
             ...
         ```
 
@@ -453,16 +459,18 @@ def is_applicable_async(cls, context: IsApplicableContext) -> bool:
         return False
 
     @classmethod
+    @deprecated("override on_pre_start instead")
     def on_pre_start_async(cls, context: OnPreStartContext) -> None:
+        pass
+
+    @classmethod
+    async def on_pre_start(cls, context: OnPreStartContext) -> None:
         """
         Called just before the language server process is started.
 
         Override to perform any preparation needed before startup - for example installing or updating server binaries,
         resolving the working directory, or injecting extra template variables into `context.variables`.
 
-        This method runs on a worker thread so perform any blocking I/O (e.g. downloading a binary, running
-        `npm install`) directly here without spawning additional threads.
-
         Mutations to `context.working_directory` and `context.variables` are picked up and used when launching the
         server process.
 
@@ -471,7 +479,11 @@ def on_pre_start_async(cls, context: OnPreStartContext) -> None:
         :param      context:    The startup context. `context.configuration`, `context.variables` and
                                 `context.working_directory` can be mutated to influence how the server is launched.
         """
-        pass
+        # Historically these methods tended to run relatively slow.
+        # We don't want to use Sublime's worker thread for this any longer.
+        # Utilize the default thread pool instead.
+        # https://docs.python.org/3/library/asyncio-dev.html#running-blocking-code
+        await run_on_threadpool(cls.on_pre_start_async, context)
 
     def __init__(self, weaksession: ref[Session]) -> None:
         """
@@ -491,14 +503,18 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
         cls.name = cls.__module__.split('.')[0]  # pyright: ignore[reportAttributeAccessIssue]
         cls.plugin_storage_path = Path(ST_STORAGE_PATH, cls.name)  # pyright: ignore[reportAttributeAccessIssue]
 
+    @deprecated("override on_initialized instead")
     def on_initialized_async(self) -> None:
+        pass
+
+    async def on_initialized(self) -> None:
         """
         Called after the `initialized` notification has been sent to the language server.
 
         Override to perform any post-initialization work, such as sending custom notifications or requests
         that depend on the server's capabilities reported in the `initialize` response.
         """
-        pass
+        self.on_initialized_async()
 
     def on_pre_send_request_async(self, request: ClientRequest, view: sublime.View | None) -> None:
         """
@@ -509,7 +525,11 @@ def on_pre_send_request_async(self, request: ClientRequest, view: sublime.View |
         """
         pass
 
+    @deprecated("override on_pre_send_response instead")
     def on_pre_send_response_async(self, response: ClientResponse) -> None:
+        pass
+
+    async def on_pre_send_response(self, response: ClientResponse) -> None:
         """
         Notifies about a response that is about to be sent to the language server.
 
@@ -518,17 +538,25 @@ def on_pre_send_response_async(self, response: ClientResponse) -> None:
 
         :param    response:    The response object containing 'method', 'params', and 'result'.
         """
-        pass
+        self.on_pre_send_response_async(response)
 
+    @deprecated("override on_pre_send_notification instead")
     def on_pre_send_notification_async(self, notification: ClientNotification) -> None:
+        pass
+
+    async def on_pre_send_notification(self, notification: ClientNotification) -> None:
         """
         Notifies about a notification that is about to be sent to the language server.
 
         :param    notification:  The notification object. The notification['params'] can be modified by the plugin.
         """
-        pass
+        self.on_pre_send_notification_async(notification)
 
+    @deprecated("override on_server_response instead")
     def on_server_response_async(self, response: ServerResponse) -> None:
+        pass
+
+    async def on_server_response(self, response: ServerResponse) -> None:
         """
         Notifies about a response message that has been received from the language server.
 
@@ -537,25 +565,37 @@ def on_server_response_async(self, response: ServerResponse) -> None:
         :param    response:  The response object to the request. The response['result'] field can be modified by the
                              plugin, before it gets further handled by the LSP package.
         """
-        pass
+        self.on_server_response_async(response)
 
+    @deprecated("override on_server_notification instead")
     def on_server_notification_async(self, notification: ServerNotification) -> None:
+        pass
+
+    async def on_server_notification(self, notification: ServerNotification) -> None:
         """
         Notifies about a notification message that has been received from the language server.
 
         :param    notification:  The notification object.
         """
-        pass
+        self.on_server_notification_async(notification)
 
+    @deprecated("override on_text_changed instead")
     def on_text_changed_async(self, session_buffer: SessionBufferProtocol) -> None:
-        """Called when the content of the session buffer has changed or a new buffer was opened (debounced)."""
         pass
 
+    async def on_text_changed(self, session_buffer: SessionBufferProtocol) -> None:
+        """Called when the content of the session buffer has changed or a new buffer was opened (debounced)."""
+        self.on_text_changed_async(session_buffer)
+
     def on_selection_modified_async(self, session_view: SessionViewProtocol) -> None:
         """Called after the selection has been modified in a view (debounced)."""
         pass
 
+    @deprecated("override on_session_end instead")
     def on_session_end_async(self, exit_code: int | None, exception: Exception | None) -> None:
+        pass
+
+    async def on_session_end(self, exit_code: int | None, exception: Exception | None) -> None:
         """
         Notifies about the session ending (also if the session has crashed). Provides an opportunity to clean up
         any stored state or delete references to the session or plugin instance that would otherwise prevent the
@@ -565,9 +605,9 @@ def on_session_end_async(self, exit_code: int | None, exception: Exception | Non
         after this method returns. In this case exit_code and exception are None.
         If the session has crashed, the exit_code and an optional exception are provided.
 
-        This API is triggered on async thread.
+        This API is triggered on the asyncio thread.
         """
-        pass
+        self.on_session_end_async(exit_code, exception)
 
 
 @deprecated('Use LspPlugin instead')