From a7f48e260ccea2aed50e8447b596baf5eea783ec Mon Sep 17 00:00:00 2001 From: Prakhar Pratyush Date: Wed, 18 Sep 2024 01:25:04 +0530 Subject: [PATCH] docs: Rename 'send_event' to 'send_event_on_commit'. This commit updates the doc to rename the 'send_event' function to 'send_ecent_on_commit'. This is required as we no longer have the send_event function and we prefer to use 'send_event_on_commit' in most cases and 'send_event_rollback_unsafe' in a few. --- docs/overview/directory-structure.md | 2 +- docs/subsystems/events-system.md | 18 +++++++++--------- docs/subsystems/notifications.md | 8 ++++---- docs/tutorials/new-feature-tutorial.md | 8 ++++---- docs/tutorials/writing-views.md | 2 +- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/overview/directory-structure.md b/docs/overview/directory-structure.md index a674ebf499..8a9f2743b3 100644 --- a/docs/overview/directory-structure.md +++ b/docs/overview/directory-structure.md @@ -25,7 +25,7 @@ paths will be familiar to Django developers. - `zerver/actions/*.py` Most code doing writes to user-facing database tables lives here. In particular, we have a policy that - all code calling `send_event` to trigger [pushing data to + all code calling `send_event_on_commit` to trigger [pushing data to clients](../subsystems/events-system.md) must live here. - `zerver/views/*.py` Most [Django views](https://docs.djangoproject.com/en/5.0/topics/http/views/). diff --git a/docs/subsystems/events-system.md b/docs/subsystems/events-system.md index 434ebbec36..623587980c 100644 --- a/docs/subsystems/events-system.md +++ b/docs/subsystems/events-system.md @@ -51,16 +51,16 @@ problems in a scalable, correct, and predictable way. ## Generation system Zulip's generation system is built around a Python function, -`send_event(realm, event, users)`. It accepts the realm (used for +`send_event_on_commit(realm, event, users)`. It accepts the realm (used for sharding), the event data structure (just a Python dictionary with some keys and value; `type` is always one of the keys but the rest depends on the specific event) and a list of user IDs for the users whose clients should receive the event. In special cases such as message delivery, the list of users will instead be a list of dicts mapping user IDs to user-specific data like whether that user was -mentioned in that message. The data passed to `send_event` are simply -marshalled as JSON and placed in the `notify_tornado` RabbitMQ queue -to be consumed by the delivery system. +mentioned in that message. The data passed to `send_event_on_commit` are +simply marshalled as JSON and placed in the `notify_tornado` RabbitMQ +queue to be consumed by the delivery system. Usually, this list of users is one of 3 things: @@ -71,8 +71,8 @@ Usually, this list of users is one of 3 things: reactions, message editing, etc.); i.e. the subscribers to a channel or the people on a direct message thread. -It is the responsibility of the caller of `send_event` to choose the -list of user IDs correctly. There can be security problems if, for +It is the responsibility of the caller of `send_event_on_commit` to choose +the list of user IDs correctly. There can be security problems if, for example, an event containing direct message content is sent to the entire organization. However, if an event isn't sent to enough clients, there will likely be user-visible real-time sync bugs. @@ -388,9 +388,9 @@ The final detail we need to ensure that `apply_events` always works correctly is to make sure that we have relevant tests for every event type that can be generated by Zulip. This can be tested manually using `test-backend --coverage BaseAction` and then -checking that all the calls to `send_event` are covered. Someday -we'll add automation that verifies this directly by inspecting the -coverage data. +checking that all the calls to `send_event_on_commit` are covered. +Someday we'll add automation that verifies this directly by inspecting +the coverage data. #### page_params diff --git a/docs/subsystems/notifications.md b/docs/subsystems/notifications.md index 59a6aa7772..77e3f0a110 100644 --- a/docs/subsystems/notifications.md +++ b/docs/subsystems/notifications.md @@ -27,11 +27,11 @@ As a reminder, the relevant part of the flow for sending messages is as follows: - `do_send_messages` is the synchronous message-sending code path, - and passing the following data in its `send_event` call: + and passing the following data in its `send_event_on_commit` call: - Data about the message's content (e.g., mentions, wildcard mentions, and alert words) and encodes it into the `UserMessage` table's `flags` structure, which is in turn passed into - `send_event` for each user receiving the message. + `send_event_on_commit` for each user receiving the message. - Data about user configuration relevant to the message, such as `online_push_user_ids` and `stream_notify_user_ids`, are included in the main event dictionary. @@ -141,8 +141,8 @@ structure of the system, when thinking about changes to it: details from the database like "which users receiving this message are online". - **Thousands of users**. Zulip supports thousands of users, and we - want to avoid `send_event()` pushing large amounts of per-user data - to Tornado via RabbitMQ for scalability reasons. + want to avoid `send_event_on_commit()` pushing large amounts of + per-user data to Tornado via RabbitMQ for scalability reasons. - **Tornado doesn't do database queries**. Because the Tornado system is an asynchronous event-driven framework, and our Django database library is synchronous, database queries are very expensive. So diff --git a/docs/tutorials/new-feature-tutorial.md b/docs/tutorials/new-feature-tutorial.md index 79c0643e00..be8fda0b0e 100644 --- a/docs/tutorials/new-feature-tutorial.md +++ b/docs/tutorials/new-feature-tutorial.md @@ -277,7 +277,7 @@ first contacts the server, the server sends the client its initial state. Subsequently, clients subscribe to "events," which can (among other things) indicate that settings have changed. -For the backend piece, we will need our action to make a call to `send_event` +For the backend piece, we will need our action to make a call to `send_event_on_commit` to send the event to clients that are active. We will also need to modify `fetch_initial_state_data` so that the new field is passed to clients. See [our event system docs](../subsystems/events-system.md) for all the @@ -299,7 +299,7 @@ help catch coding mistakes, not to check for bad user input. After updating the given realm field, `do_set_realm_property` creates an 'update' event with the name of the property and the new value. It -then calls `send_event`, passing the event and the list of users whose +then calls `send_event_on_commit`, passing the event and the list of users whose browser sessions should be notified as the second argument. The latter argument can be a single user (if the setting is a personal one, like time display format), members in a particular channel only or all @@ -327,7 +327,7 @@ def do_set_realm_property( property=name, value=value, ) - send_event(realm, event, active_user_ids(realm)) + send_event_on_commit(realm, event, active_user_ids(realm)) ``` If the new realm property being added does not fit into the @@ -351,7 +351,7 @@ def do_set_realm_authentication_methods( property='default', data=dict(authentication_methods=realm.authentication_methods_dict()) ) - send_event(realm, event, active_user_ids(realm)) + send_event_on_commit(realm, event, active_user_ids(realm)) ``` ### Update application state diff --git a/docs/tutorials/writing-views.md b/docs/tutorials/writing-views.md index 6f78fd3cb6..1cbbe1b67a 100644 --- a/docs/tutorials/writing-views.md +++ b/docs/tutorials/writing-views.md @@ -332,7 +332,7 @@ def update_realm( ``` `realm.save()` actually saves the changes to the realm to the -database, and `send_event` sends the event to active clients belonging +database, and `send_event_on_commit` sends the event to active clients belonging to the provided list of users (in this case, all active users in the Zulip realm).