From f74212ef659d8c5f741923faa39cc6b1a9ba4049 Mon Sep 17 00:00:00 2001 From: babolivier Date: Wed, 1 Dec 2021 14:13:29 +0000 Subject: [PATCH] deploy: 153194c7717d8016b0eb974c81b1baee7dc1917d --- develop/404.html | 2 +- develop/CAPTCHA_SETUP.html | 2 +- develop/MSC1711_certificates_FAQ.html | 2 +- develop/admin_api/account_validity.html | 2 +- develop/admin_api/delete_group.html | 2 +- develop/admin_api/event_reports.html | 2 +- develop/admin_api/media_admin_api.html | 2 +- develop/admin_api/purge_history_api.html | 2 +- develop/admin_api/register_api.html | 2 +- develop/admin_api/room_membership.html | 2 +- develop/admin_api/rooms.html | 2 +- develop/admin_api/server_notices.html | 2 +- develop/admin_api/statistics.html | 2 +- develop/admin_api/user_admin_api.html | 2 +- develop/admin_api/version_api.html | 2 +- develop/application_services.html | 2 +- develop/auth_chain_difference_algorithm.html | 2 +- develop/code_style.html | 2 +- develop/consent_tracking.html | 2 +- develop/delegate.html | 2 +- develop/deprecation_policy.html | 2 +- develop/development/cas.html | 2 +- develop/development/contributing_guide.html | 2 +- develop/development/database_schema.html | 2 +- .../development/experimental_features.html | 2 +- develop/development/git.html | 2 +- .../internal_documentation/index.html | 2 +- develop/development/room-dag-concepts.html | 2 +- develop/development/saml.html | 2 +- develop/development/url_previews.html | 2 +- develop/federate.html | 2 +- develop/index.html | 2 +- develop/jwt.html | 2 +- develop/log_contexts.html | 2 +- develop/manhole.html | 2 +- develop/media_repository.html | 2 +- develop/message_retention_policies.html | 2 +- develop/metrics-howto.html | 2 +- .../modules/account_validity_callbacks.html | 2 +- ...ackground_update_controller_callbacks.html | 302 ++++++++++++++++++ develop/modules/index.html | 2 +- .../password_auth_provider_callbacks.html | 6 +- develop/modules/porting_legacy_module.html | 6 +- .../modules/presence_router_callbacks.html | 2 +- develop/modules/spam_checker_callbacks.html | 2 +- .../modules/third_party_rules_callbacks.html | 2 +- develop/modules/writing_a_module.html | 2 +- develop/openid.html | 2 +- develop/opentracing.html | 2 +- develop/password_auth_providers.html | 2 +- develop/postgres.html | 2 +- develop/print.html | 49 ++- develop/replication.html | 2 +- develop/reverse_proxy.html | 2 +- develop/room_and_user_statistics.html | 2 +- develop/searchindex.js | 2 +- develop/searchindex.json | 2 +- develop/server_notices.html | 2 +- develop/setup/forward_proxy.html | 2 +- develop/setup/installation.html | 2 +- develop/sso_mapping_providers.html | 2 +- develop/structured_logging.html | 2 +- develop/synctl_workers.html | 2 +- develop/systemd-with-workers/index.html | 2 +- develop/tcp_replication.html | 2 +- develop/templates.html | 2 +- develop/turn-howto.html | 2 +- develop/upgrade.html | 2 +- .../admin_api/background_updates.html | 2 +- .../usage/administration/admin_api/index.html | 2 +- .../admin_api/registration_tokens.html | 2 +- develop/usage/administration/index.html | 2 +- develop/usage/administration/request_log.html | 2 +- .../homeserver_sample_config.html | 2 +- develop/usage/configuration/index.html | 2 +- .../configuration/logging_sample_config.html | 2 +- .../user_authentication/index.html | 2 +- .../single_sign_on/cas.html | 2 +- .../single_sign_on/index.html | 2 +- .../single_sign_on/saml.html | 2 +- develop/user_directory.html | 2 +- develop/welcome_and_overview.html | 2 +- develop/workers.html | 2 +- 83 files changed, 435 insertions(+), 86 deletions(-) create mode 100644 develop/modules/background_update_controller_callbacks.html diff --git a/develop/404.html b/develop/404.html index c39141e953..96417bb629 100644 --- a/develop/404.html +++ b/develop/404.html @@ -101,7 +101,7 @@ diff --git a/develop/CAPTCHA_SETUP.html b/develop/CAPTCHA_SETUP.html index adec4d1711..b07a365d74 100644 --- a/develop/CAPTCHA_SETUP.html +++ b/develop/CAPTCHA_SETUP.html @@ -99,7 +99,7 @@ diff --git a/develop/MSC1711_certificates_FAQ.html b/develop/MSC1711_certificates_FAQ.html index 61bc3f526c..dfb4ecbd9e 100644 --- a/develop/MSC1711_certificates_FAQ.html +++ b/develop/MSC1711_certificates_FAQ.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/account_validity.html b/develop/admin_api/account_validity.html index b1f6dedf63..0c1b5ffd29 100644 --- a/develop/admin_api/account_validity.html +++ b/develop/admin_api/account_validity.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/delete_group.html b/develop/admin_api/delete_group.html index f48720c8b3..d2f899f0ff 100644 --- a/develop/admin_api/delete_group.html +++ b/develop/admin_api/delete_group.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/event_reports.html b/develop/admin_api/event_reports.html index f8ca18717e..81cac5e48f 100644 --- a/develop/admin_api/event_reports.html +++ b/develop/admin_api/event_reports.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/media_admin_api.html b/develop/admin_api/media_admin_api.html index 321d07c6dd..a4ae2d566c 100644 --- a/develop/admin_api/media_admin_api.html +++ b/develop/admin_api/media_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/purge_history_api.html b/develop/admin_api/purge_history_api.html index 0ab311d650..724b3e7e6c 100644 --- a/develop/admin_api/purge_history_api.html +++ b/develop/admin_api/purge_history_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/register_api.html b/develop/admin_api/register_api.html index cd2a137112..ccb475a9fd 100644 --- a/develop/admin_api/register_api.html +++ b/develop/admin_api/register_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/room_membership.html b/develop/admin_api/room_membership.html index d043e2b97f..5ba707bef2 100644 --- a/develop/admin_api/room_membership.html +++ b/develop/admin_api/room_membership.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/rooms.html b/develop/admin_api/rooms.html index 8e31f898fd..6f7d8a15d8 100644 --- a/develop/admin_api/rooms.html +++ b/develop/admin_api/rooms.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/server_notices.html b/develop/admin_api/server_notices.html index 85182a55b2..f49f11de10 100644 --- a/develop/admin_api/server_notices.html +++ b/develop/admin_api/server_notices.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/statistics.html b/develop/admin_api/statistics.html index 116e56bfc9..fbb18220fa 100644 --- a/develop/admin_api/statistics.html +++ b/develop/admin_api/statistics.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/user_admin_api.html b/develop/admin_api/user_admin_api.html index f9291da868..d92d7b6998 100644 --- a/develop/admin_api/user_admin_api.html +++ b/develop/admin_api/user_admin_api.html @@ -99,7 +99,7 @@ diff --git a/develop/admin_api/version_api.html b/develop/admin_api/version_api.html index 92b88c02fd..052de18fbc 100644 --- a/develop/admin_api/version_api.html +++ b/develop/admin_api/version_api.html @@ -99,7 +99,7 @@ diff --git a/develop/application_services.html b/develop/application_services.html index 4d1b59f8ea..2c64e8f716 100644 --- a/develop/application_services.html +++ b/develop/application_services.html @@ -99,7 +99,7 @@ diff --git a/develop/auth_chain_difference_algorithm.html b/develop/auth_chain_difference_algorithm.html index 5460248b13..dbff0bad94 100644 --- a/develop/auth_chain_difference_algorithm.html +++ b/develop/auth_chain_difference_algorithm.html @@ -99,7 +99,7 @@ diff --git a/develop/code_style.html b/develop/code_style.html index 884f0a4c1e..8e66d7ab75 100644 --- a/develop/code_style.html +++ b/develop/code_style.html @@ -99,7 +99,7 @@ diff --git a/develop/consent_tracking.html b/develop/consent_tracking.html index 55e0dbb092..fe9306b7ae 100644 --- a/develop/consent_tracking.html +++ b/develop/consent_tracking.html @@ -99,7 +99,7 @@ diff --git a/develop/delegate.html b/develop/delegate.html index 8a30c2cdf2..18952abaff 100644 --- a/develop/delegate.html +++ b/develop/delegate.html @@ -99,7 +99,7 @@ diff --git a/develop/deprecation_policy.html b/develop/deprecation_policy.html index 7d40f778d6..c9a6226f9d 100644 --- a/develop/deprecation_policy.html +++ b/develop/deprecation_policy.html @@ -99,7 +99,7 @@ diff --git a/develop/development/cas.html b/develop/development/cas.html index 896e2756a5..a7d2112501 100644 --- a/develop/development/cas.html +++ b/develop/development/cas.html @@ -99,7 +99,7 @@ diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index 9439edb8f3..31477d12bb 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -99,7 +99,7 @@ diff --git a/develop/development/database_schema.html b/develop/development/database_schema.html index ebe07774d8..3ac816c67e 100644 --- a/develop/development/database_schema.html +++ b/develop/development/database_schema.html @@ -99,7 +99,7 @@ diff --git a/develop/development/experimental_features.html b/develop/development/experimental_features.html index 7995ac0eb6..9838b8abd5 100644 --- a/develop/development/experimental_features.html +++ b/develop/development/experimental_features.html @@ -99,7 +99,7 @@ diff --git a/develop/development/git.html b/develop/development/git.html index f53a79675a..17d1df82db 100644 --- a/develop/development/git.html +++ b/develop/development/git.html @@ -99,7 +99,7 @@ diff --git a/develop/development/internal_documentation/index.html b/develop/development/internal_documentation/index.html index 9acd99aeb3..eb880b63ea 100644 --- a/develop/development/internal_documentation/index.html +++ b/develop/development/internal_documentation/index.html @@ -99,7 +99,7 @@ diff --git a/develop/development/room-dag-concepts.html b/develop/development/room-dag-concepts.html index 44f8fcd4ae..8fba02aa5b 100644 --- a/develop/development/room-dag-concepts.html +++ b/develop/development/room-dag-concepts.html @@ -99,7 +99,7 @@ diff --git a/develop/development/saml.html b/develop/development/saml.html index 555c34889e..1531e7b117 100644 --- a/develop/development/saml.html +++ b/develop/development/saml.html @@ -99,7 +99,7 @@ diff --git a/develop/development/url_previews.html b/develop/development/url_previews.html index 63b39e5da5..0b89c11069 100644 --- a/develop/development/url_previews.html +++ b/develop/development/url_previews.html @@ -99,7 +99,7 @@ diff --git a/develop/federate.html b/develop/federate.html index da53c865b0..06100b7808 100644 --- a/develop/federate.html +++ b/develop/federate.html @@ -99,7 +99,7 @@ diff --git a/develop/index.html b/develop/index.html index ec52df45bd..9392ba7fa1 100644 --- a/develop/index.html +++ b/develop/index.html @@ -99,7 +99,7 @@ diff --git a/develop/jwt.html b/develop/jwt.html index 2b6d0a0353..aade266eb2 100644 --- a/develop/jwt.html +++ b/develop/jwt.html @@ -99,7 +99,7 @@ diff --git a/develop/log_contexts.html b/develop/log_contexts.html index 0f840e3397..5a87c74e21 100644 --- a/develop/log_contexts.html +++ b/develop/log_contexts.html @@ -99,7 +99,7 @@ diff --git a/develop/manhole.html b/develop/manhole.html index cf627ebdf4..13b213469c 100644 --- a/develop/manhole.html +++ b/develop/manhole.html @@ -99,7 +99,7 @@ diff --git a/develop/media_repository.html b/develop/media_repository.html index d2edb6b507..2a9ec55eec 100644 --- a/develop/media_repository.html +++ b/develop/media_repository.html @@ -99,7 +99,7 @@ diff --git a/develop/message_retention_policies.html b/develop/message_retention_policies.html index 3014248aa4..18f50ca030 100644 --- a/develop/message_retention_policies.html +++ b/develop/message_retention_policies.html @@ -99,7 +99,7 @@ diff --git a/develop/metrics-howto.html b/develop/metrics-howto.html index 68ec94de63..167d63c4dc 100644 --- a/develop/metrics-howto.html +++ b/develop/metrics-howto.html @@ -99,7 +99,7 @@ diff --git a/develop/modules/account_validity_callbacks.html b/develop/modules/account_validity_callbacks.html index 0eea641b96..91477e6ae8 100644 --- a/develop/modules/account_validity_callbacks.html +++ b/develop/modules/account_validity_callbacks.html @@ -99,7 +99,7 @@ diff --git a/develop/modules/background_update_controller_callbacks.html b/develop/modules/background_update_controller_callbacks.html new file mode 100644 index 0000000000..4168bd51e9 --- /dev/null +++ b/develop/modules/background_update_controller_callbacks.html @@ -0,0 +1,302 @@ + + + + + + Background update controller callbacks - Synapse + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + +
+
+ +
+ +
+ +

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

+
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

+
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

+
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.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/develop/modules/index.html b/develop/modules/index.html index eb6e45f591..2a1cf292ee 100644 --- a/develop/modules/index.html +++ b/develop/modules/index.html @@ -99,7 +99,7 @@ diff --git a/develop/modules/password_auth_provider_callbacks.html b/develop/modules/password_auth_provider_callbacks.html index 4d22d61535..7badb7742b 100644 --- a/develop/modules/password_auth_provider_callbacks.html +++ b/develop/modules/password_auth_provider_callbacks.html @@ -99,7 +99,7 @@ @@ -345,7 +345,7 @@ class MyAuthProvider: - @@ -363,7 +363,7 @@ class MyAuthProvider: - diff --git a/develop/modules/porting_legacy_module.html b/develop/modules/porting_legacy_module.html index 9605b0e5c6..6a19427fc1 100644 --- a/develop/modules/porting_legacy_module.html +++ b/develop/modules/porting_legacy_module.html @@ -99,7 +99,7 @@ @@ -205,7 +205,7 @@ for more info).