From 894ac30a4e44e53a8116e6597f74a0d58ae495c6 Mon Sep 17 00:00:00 2001 From: MatMaul Date: Tue, 14 Mar 2023 16:43:55 +0000 Subject: deploy: 8b1af08c6ed141101d127bcf9909f23b2b621510 --- latest/modules/writing_a_module.html | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'latest/modules/writing_a_module.html') diff --git a/latest/modules/writing_a_module.html b/latest/modules/writing_a_module.html index 1e2119a40c..bc8627c62e 100644 --- a/latest/modules/writing_a_module.html +++ b/latest/modules/writing_a_module.html @@ -207,6 +207,54 @@ the callback name as the argument name and the function as its value. A register_[...]_callbacks method exists for each category.

Callbacks for each category can be found on their respective page of the Synapse documentation website.

+

Caching

+

Added in Synapse 1.74.0.

+

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.

+

Functions that need to be wrapped with a cache need to be decorated with a @cached() +decorator (which can be imported from synapse.module_api) and registered with the +ModuleApi.register_cached_function +API when initialising the module. If the module needs to invalidate an entry in a cache, +it needs to use the ModuleApi.invalidate_cache +API, with the function to invalidate the cache of and the key(s) of the entry to +invalidate.

+

Below is an example of a simple module using a cached function:

+
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,))
+
+

See the cached docstring for more details.

-- cgit 1.5.1