diff options
Diffstat (limited to '')
| -rw-r--r-- | develop/print.html | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/develop/print.html b/develop/print.html index 1afc6e18d0..6f8e506c8a 100644 --- a/develop/print.html +++ b/develop/print.html @@ -9373,6 +9373,54 @@ the callback name as the argument name and the function as its value. A <code>register_[...]_callbacks</code> method exists for each category.</p> <p>Callbacks for each category can be found on their respective page of the <a href="https://matrix-org.github.io/synapse">Synapse documentation website</a>.</p> +<h2 id="caching-1"><a class="header" href="#caching-1">Caching</a></h2> +<p><em>Added in Synapse 1.74.0.</em></p> +<p>Modules can leverage Synapse's caching tools to manage their own cached functions. This +can be helpful for modules that need to repeatedly request the same data from the database +or a remote service.</p> +<p>Functions that need to be wrapped with a cache need to be decorated with a <code>@cached()</code> +decorator (which can be imported from <code>synapse.module_api</code>) and registered with the +<a href="https://github.com/matrix-org/synapse/blob/release-v1.77/synapse/module_api/__init__.py#L888"><code>ModuleApi.register_cached_function</code></a> +API when initialising the module. If the module needs to invalidate an entry in a cache, +it needs to use the <a href="https://github.com/matrix-org/synapse/blob/release-v1.77/synapse/module_api/__init__.py#L904"><code>ModuleApi.invalidate_cache</code></a> +API, with the function to invalidate the cache of and the key(s) of the entry to +invalidate.</p> +<p>Below is an example of a simple module using a cached function:</p> +<pre><code class="language-python">from typing import Any +from synapse.module_api import cached, ModuleApi + +class MyModule: + def __init__(self, config: Any, api: ModuleApi): + self.api = api + + # Register the cached function so Synapse knows how to correctly invalidate + # entries for it. + self.api.register_cached_function(self.get_user_from_id) + + @cached() + async def get_department_for_user(self, user_id: str) -> str: + """A function with a cache.""" + # Request a department from an external service. + return await self.http_client.get_json( + "https://int.example.com/users", {"user_id": user_id) + )["department"] + + async def do_something_with_users(self) -> None: + """Calls the cached function and then invalidates an entry in its cache.""" + + user_id = "@alice:example.com" + + # Get the user. Since get_department_for_user is wrapped with a cache, + # the return value for this user_id will be cached. + department = await self.get_department_for_user(user_id) + + # Do something with `department`... + + # Let's say something has changed with our user, and the entry we have for + # them in the cache is out of date, so we want to invalidate it. + await self.api.invalidate_cache(self.get_department_for_user, (user_id,)) +</code></pre> +<p>See the <a href="https://github.com/matrix-org/synapse/blob/release-v1.77/synapse/module_api/__init__.py#L190"><code>cached</code> docstring</a> for more details.</p> <div style="break-before: page; page-break-before: always;"></div><h1 id="spam-checker-callbacks"><a class="header" href="#spam-checker-callbacks">Spam checker callbacks</a></h1> <p>Spam checker callbacks allow module developers to implement spam mitigation actions for Synapse instances. Spam checker callbacks can be registered using the module API's |