paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 05:53:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Tweak some documentation around send_event.

Browse Source
This commit is contained in:
Tim Abbott
2024-09-20 15:28:18 -07:00
parent a7f48e260c
commit 51d0dfb504
4 changed files with 27 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/subsystems/events-system.md
View File

@@ -77,6 +77,11 @@ 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.
As indicated in the name, `send_event_on_commit` is intended to be
called inside the database transaction that is changing the state
itself; this design ensures that the event is only sent if the
transaction successfully commits.
Most of the hard work in event generation is about defining consistent
event dictionaries that are clear, readable, will be useful to the
wide range of possible clients, and make it easy for developers.

12
docs/tutorials/new-feature-tutorial.md
View File

@@ -277,11 +277,13 @@ 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_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
gory details.
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
(The event is only sent after the current database transaction
commits, hence the name). 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 gory details.
Anyway, getting back to implementation details...

6
docs/tutorials/writing-views.md
View File

@@ -332,9 +332,9 @@ def update_realm(
```
`realm.save()` actually saves the changes to the realm to the
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).
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), once the current transaction completes.
### Calling from the web application

17
zerver/lib/test_classes.py
View File

@@ -2052,11 +2052,18 @@ class ZulipTestCase(ZulipTestCaseMixin, TestCase):
# So explicitly change parameter name to 'notice' to work around this problem
with (
mock.patch("zerver.tornado.event_queue.process_notification", lst.append),
# Some `send_event_rollback_unsafe` calls need to be executed only after the
# current transaction commits (using `on_commit` hooks). Because the transaction
# in Django tests never commits (rather, gets rolled back after the test completes),
# such events would never be sent in tests, and we would be unable to verify them.
# Hence, we use this helper to make sure the `send_event_rollback_unsafe` calls actually run.
# Some `send_event_rollback_unsafe` calls need to be
# executed only after the current transaction commits
# (mainly those using the `send_event_on_commit` wrapper, which
# sends the actual event inside an `on_commit` hook).
#
# Because the outer transaction in Django tests never
# commits (it gets rolled back when the test completes
# to restore the database to the desired state for the
# next test), such events would never be sent in
# tests, and we would be unable to verify them.
# Hence, we use this helper to make sure the
# `send_event_rollback_unsafe` calls actually run.
self.captureOnCommitCallbacks(execute=True),
):
yield lst