From 0c8759bbb6eda02433ae5f32525b97fcf29005f1 Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Wed, 27 Aug 2025 20:27:45 -0500 Subject: [PATCH] Remove mentions of Synapse logcontext rules (the distinction doesn't matter anymore) --- synapse/logging/context.py | 6 ----- synapse/metrics/background_process_metrics.py | 9 +++---- synapse/module_api/__init__.py | 26 ++++++------------- synapse/util/async_helpers.py | 21 ++------------- synapse/util/caches/deferred_cache.py | 3 --- synapse/util/caches/response_cache.py | 6 ++--- 6 files changed, 15 insertions(+), 56 deletions(-) diff --git a/synapse/logging/context.py b/synapse/logging/context.py index a739bdd937..b91a800630 100644 --- a/synapse/logging/context.py +++ b/synapse/logging/context.py @@ -868,9 +868,6 @@ def defer_to_thread( logcontext (so its CPU usage metrics will get attributed to the current logcontext). `f` should preserve the logcontext it is given. - The result deferred follows the Synapse logcontext rules: you should `yield` - on it. - Args: reactor: The reactor in whose main thread the Deferred will be invoked, and whose threadpool we should use for the function. @@ -908,9 +905,6 @@ def defer_to_threadpool( logcontext (so its CPU usage metrics will get attributed to the current logcontext). `f` should preserve the logcontext it is given. - The result deferred follows the Synapse logcontext rules: you should `yield` - on it. - Args: reactor: The reactor in whose main thread the Deferred will be invoked. Normally this will be hs.get_reactor(). diff --git a/synapse/metrics/background_process_metrics.py b/synapse/metrics/background_process_metrics.py index f7f2d88885..7d98409c62 100644 --- a/synapse/metrics/background_process_metrics.py +++ b/synapse/metrics/background_process_metrics.py @@ -223,10 +223,9 @@ def run_as_background_process( 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). + It returns a Deferred which completes when the function completes, 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). Args: desc: a description for this background process type @@ -241,8 +240,6 @@ def run_as_background_process( 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. """ async def run() -> Optional[R]: diff --git a/synapse/module_api/__init__.py b/synapse/module_api/__init__.py index 9309aa9394..4a76f9f56f 100644 --- a/synapse/module_api/__init__.py +++ b/synapse/module_api/__init__.py @@ -237,10 +237,9 @@ def run_as_background_process( 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). + It returns a Deferred which completes when the function completes, 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). Args: desc: a description for this background process type @@ -255,8 +254,6 @@ def run_as_background_process( 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. """ logger.warning( @@ -1375,9 +1372,7 @@ class ModuleApi: Args: f: The function to call repeatedly. f can be either synchronous or - asynchronous, and must follow Synapse's logcontext rules. - More info about logcontexts is available at - https://element-hq.github.io/synapse/latest/log_contexts.html + asynchronous. msec: How long to wait between calls in milliseconds. *args: Positional arguments to pass to function. desc: The background task's description. Default to the function's name. @@ -1431,9 +1426,7 @@ class ModuleApi: Args: msec: How long to wait before calling, in milliseconds. f: The function to call once. f can be either synchronous or - asynchronous, and must follow Synapse's logcontext rules. - More info about logcontexts is available at - https://element-hq.github.io/synapse/latest/log_contexts.html + asynchronous. *args: Positional arguments to pass to function. desc: The background task's description. Default to the function's name. **kwargs: Keyword arguments to pass to function. @@ -1668,10 +1661,9 @@ class ModuleApi: 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). + It returns a Deferred which completes when the function completes, 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). Args: desc: a description for this background process type @@ -1686,8 +1678,6 @@ class ModuleApi: 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, self.server_name, func, *args, bg_start_span=bg_start_span, **kwargs diff --git a/synapse/util/async_helpers.py b/synapse/util/async_helpers.py index e596e1ed20..0f0e2ea9aa 100644 --- a/synapse/util/async_helpers.py +++ b/synapse/util/async_helpers.py @@ -84,9 +84,6 @@ class AbstractObservableDeferred(Generic[_T], metaclass=abc.ABCMeta): This returns a brand new deferred that is resolved when the underlying deferred is resolved. Interacting with the returned deferred does not effect the underlying deferred. - - Note that the returned Deferred doesn't follow the Synapse logcontext rules - - you will probably want to `make_deferred_yieldable` it. """ ... @@ -100,11 +97,6 @@ class ObservableDeferred(Generic[_T], AbstractObservableDeferred[_T]): Cancelling or otherwise resolving an observer will not affect the original ObservableDeferred. - - NB that it does not attempt to do anything with logcontexts; in general - you should probably make_deferred_yieldable the deferreds - returned by `observe`, and ensure that the original deferred runs its - callbacks in the sentinel logcontext. """ __slots__ = ["_deferred", "_observers", "_result"] @@ -861,16 +853,12 @@ def stop_cancellation(deferred: "defer.Deferred[T]") -> "defer.Deferred[T]": """Prevent a `Deferred` from being cancelled by wrapping it in another `Deferred`. Args: - deferred: The `Deferred` to protect against cancellation. Must not follow the - Synapse logcontext rules. + deferred: The `Deferred` to protect against cancellation. Returns: A new `Deferred`, which will contain the result of the original `Deferred`. The new `Deferred` will not propagate cancellation through to the original. When cancelled, the new `Deferred` will fail with a `CancelledError`. - - The new `Deferred` will not follow the Synapse logcontext rules and should be - wrapped with `make_deferred_yieldable`. """ new_deferred: "defer.Deferred[T]" = defer.Deferred() deferred.chainDeferred(new_deferred) @@ -896,8 +884,7 @@ def delay_cancellation(awaitable: Awaitable[T]) -> Awaitable[T]: resolve with a `CancelledError` until the original awaitable resolves. Args: - deferred: The coroutine or `Deferred` to protect against cancellation. May - optionally follow the Synapse logcontext rules. + deferred: The coroutine or `Deferred` to protect against cancellation. Returns: A new `Deferred`, which will contain the result of the original coroutine or @@ -906,10 +893,6 @@ def delay_cancellation(awaitable: Awaitable[T]) -> Awaitable[T]: When cancelled, the new `Deferred` will wait until the original coroutine or `Deferred` resolves before failing with a `CancelledError`. - - The new `Deferred` will follow the Synapse logcontext rules if `awaitable` - follows the Synapse logcontext rules. Otherwise the new `Deferred` should be - wrapped with `make_deferred_yieldable`. """ # First, convert the awaitable into a `Deferred`. diff --git a/synapse/util/caches/deferred_cache.py b/synapse/util/caches/deferred_cache.py index 92d446ce2a..7e1c311a4a 100644 --- a/synapse/util/caches/deferred_cache.py +++ b/synapse/util/caches/deferred_cache.py @@ -295,9 +295,6 @@ class DeferredCache(Generic[KT, VT]): *original* `value`, (c) any future calls to `get()` will complete with the result from the *new* `value`. - It is expected that `value` does *not* follow the synapse logcontext rules - ie, - if it is incomplete, it runs its callbacks in the sentinel context. - Args: key: Key to be set value: a deferred which will complete with a result to add to the cache diff --git a/synapse/util/caches/response_cache.py b/synapse/util/caches/response_cache.py index 49a9151916..6776c53b0b 100644 --- a/synapse/util/caches/response_cache.py +++ b/synapse/util/caches/response_cache.py @@ -234,11 +234,9 @@ class ResponseCache(Generic[KV]): ) -> RV: """Wrap together a *get* and *set* call, taking care of logcontexts - First looks up the key in the cache, and if it is present makes it - follow the synapse logcontext rules and returns it. + First looks up the key in the cache, and if present, returns it. - Otherwise, makes a call to *callback(*args, **kwargs)*, which should - follow the synapse logcontext rules, and adds the result to the cache. + Otherwise, makes a call to *callback(*args, **kwargs)* and adds the result to the cache. Example usage: