diff options
Diffstat (limited to 'docs/modules')
| -rw-r--r-- | docs/modules/background_update_controller_callbacks.md | 71 | ||||
| -rw-r--r-- | docs/modules/writing_a_module.md | 12 |
2 files changed, 6 insertions, 77 deletions
diff --git a/docs/modules/background_update_controller_callbacks.md b/docs/modules/background_update_controller_callbacks.md deleted file mode 100644 index b3e7c259f4..0000000000 --- a/docs/modules/background_update_controller_callbacks.md +++ /dev/null @@ -1,71 +0,0 @@ -# Background update controller callbacks - -Background update controller callbacks allow module developers to control (e.g. rate-limit) -how database background updates are run. A database background update is an operation -Synapse runs on its database in the background after it starts. It's usually used to run -database operations that would take too long if they were run at the same time as schema -updates (which are run on startup) and delay Synapse's startup too much: populating a -table with a big amount of data, adding an index on a big table, deleting superfluous data, -etc. - -Background update controller callbacks can be registered using the module API's -`register_background_update_controller_callbacks` method. Only the first module (in order -of appearance in Synapse's configuration file) calling this method can register background -update controller callbacks, subsequent calls are ignored. - -The available background update controller callbacks are: - -### `on_update` - -_First introduced in Synapse v1.49.0_ - -```python -def on_update(update_name: str, database_name: str, one_shot: bool) -> AsyncContextManager[int] -``` - -Called when about to do an iteration of a background update. The module is given the name -of the update, the name of the database, and a flag to indicate whether the background -update will happen in one go and may take a long time (e.g. creating indices). If this last -argument is set to `False`, the update will be run in batches. - -The module must return an async context manager. It will be entered before Synapse runs a -background update; this should return the desired duration of the iteration, in -milliseconds. - -The context manager will be exited when the iteration completes. Note that the duration -returned by the context manager is a target, and an iteration may take substantially longer -or shorter. If the `one_shot` flag is set to `True`, the duration returned is ignored. - -__Note__: Unlike most module callbacks in Synapse, this one is _synchronous_. This is -because asynchronous operations are expected to be run by the async context manager. - -This callback is required when registering any other background update controller callback. - -### `default_batch_size` - -_First introduced in Synapse v1.49.0_ - -```python -async def default_batch_size(update_name: str, database_name: str) -> int -``` - -Called before the first iteration of a background update, with the name of the update and -of the database. The module must return the number of elements to process in this first -iteration. - -If this callback is not defined, Synapse will use a default value of 100. - -### `min_batch_size` - -_First introduced in Synapse v1.49.0_ - -```python -async def min_batch_size(update_name: str, database_name: str) -> int -``` - -Called before running a new batch for a background update, with the name of the update and -of the database. The module must return an integer representing the minimum number of -elements to process in this iteration. This number must be at least 1, and is used to -ensure that progress is always made. - -If this callback is not defined, Synapse will use a default value of 100. diff --git a/docs/modules/writing_a_module.md b/docs/modules/writing_a_module.md index e7c0ffad58..7764e06692 100644 --- a/docs/modules/writing_a_module.md +++ b/docs/modules/writing_a_module.md @@ -71,15 +71,15 @@ Modules **must** register their web resources in their `__init__` method. ## Registering a callback Modules can use Synapse's module API to register callbacks. Callbacks are functions that -Synapse will call when performing specific actions. Callbacks must be asynchronous (unless -specified otherwise), and are split in categories. A single module may implement callbacks -from multiple categories, and is under no obligation to implement all callbacks from the -categories it registers callbacks for. +Synapse will call when performing specific actions. Callbacks must be asynchronous, and +are split in categories. A single module may implement callbacks from multiple categories, +and is under no obligation to implement all callbacks from the categories it registers +callbacks for. Modules can register callbacks using one of the module API's `register_[...]_callbacks` methods. The callback functions are passed to these methods as keyword arguments, with -the callback name as the argument name and the function as its value. A -`register_[...]_callbacks` method exists for each category. +the callback name as the argument name and the function as its value. This is demonstrated +in the example below. A `register_[...]_callbacks` method exists for each category. Callbacks for each category can be found on their respective page of the [Synapse documentation website](https://matrix-org.github.io/synapse). \ No newline at end of file |