Update `LoggingTransaction.call_after` and `call_on_exception` docstrings (#12315)

Document the behaviour of `LoggingTransaction.call_after` and
`LoggingTransaction.call_on_exception` when transactions are retried.

Signed-off-by: Sean Quah <seanq@element.io>
This commit is contained in:
Sean Quah 2022-03-29 12:31:05 +01:00 committed by GitHub
parent a2b00a4486
commit 8a519f8abc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 3 deletions

1
changelog.d/12315.doc Normal file
View File

@ -0,0 +1 @@
Document the behaviour of `LoggingTransaction.call_after` and `LoggingTransaction.call_on_exception` methods when transactions are retried.

View File

@ -241,9 +241,17 @@ class LoggingTransaction:
self.exception_callbacks = exception_callbacks
def call_after(self, callback: Callable[..., object], *args: Any, **kwargs: Any):
"""Call the given callback on the main twisted thread after the
transaction has finished. Used to invalidate the caches on the
correct thread.
"""Call the given callback on the main twisted thread after the transaction has
finished.
Mostly used to invalidate the caches on the correct thread.
Note that transactions may be retried a few times if they encounter database
errors such as serialization failures. Callbacks given to `call_after`
will accumulate across transaction attempts and will _all_ be called once a
transaction attempt succeeds, regardless of whether previous transaction
attempts failed. Otherwise, if all transaction attempts fail, all
`call_on_exception` callbacks will be run instead.
"""
# if self.after_callbacks is None, that means that whatever constructed the
# LoggingTransaction isn't expecting there to be any callbacks; assert that
@ -254,6 +262,15 @@ class LoggingTransaction:
def call_on_exception(
self, callback: Callable[..., object], *args: Any, **kwargs: Any
):
"""Call the given callback on the main twisted thread after the transaction has
failed.
Note that transactions may be retried a few times if they encounter database
errors such as serialization failures. Callbacks given to `call_on_exception`
will accumulate across transaction attempts and will _all_ be called once the
final transaction attempt fails. No `call_on_exception` callbacks will be run
if any transaction attempt succeeds.
"""
# if self.exception_callbacks is None, that means that whatever constructed the
# LoggingTransaction isn't expecting there to be any callbacks; assert that
# is not the case.