Export run_as_background_process from the module API

changelog.d/15577.misc

@@ -0,0 +1 @@
+Expose `run_as_background_process` in the module API.

synapse/module_api/__init__.py

@@ -17,6 +17,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
+    Awaitable,
     Callable,
     Collection,
     Dict,
@@ -1666,6 +1667,46 @@ async def set_displayname(
             deactivation=deactivation,
         )
 
+    R = TypeVar("R")
+
+    def run_as_background_process(
+        self,
+        desc: str,
+        func: Callable[..., Awaitable[Optional[R]]],
+        *args: Any,
+        bg_start_span: bool = True,
+        **kwargs: Any,
+    ) -> "defer.Deferred[Optional[R]]":
+        """Run the given function in its own logcontext, with resource metrics
+
+        This should be used to wrap processes which are fired off to run in the
+        background, instead of being associated with a particular request.
+
+        It returns a Deferred which completes when the function completes, but it doesn't
+        follow the synapse logcontext rules, which makes it appropriate for passing to
+        clock.looping_call and friends (or for firing-and-forgetting in the middle of a
+        normal synapse async function).
+
+        Added in Synapse v1.84.0
+
+        Args:
+            desc: a description for this background process type
+            func: a function, which may return a Deferred or a coroutine
+            bg_start_span: Whether to start an opentracing span. Defaults to True.
+                Should only be disabled for processes that will not log to or tag
+                a span.
+            args: positional args for func
+            kwargs: keyword args for func
+
+        Returns:
+            Deferred which returns the result of func, or `None` if func raises.
+            Note that the returned Deferred does not follow the synapse logcontext
+            rules.
+        """
+        return run_as_background_process(
+            desc, func, *args, bg_start_span=bg_start_span, **kwargs
+        )
+
 
 class PublicRoomListManager:
     """Contains methods for adding to, removing from and querying whether a room