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 self.exception_callbacks = exception_callbacks
def call_after(self, callback: Callable[..., object], *args: Any, **kwargs: Any): def call_after(self, callback: Callable[..., object], *args: Any, **kwargs: Any):
"""Call the given callback on the main twisted thread after the """Call the given callback on the main twisted thread after the transaction has
transaction has finished. Used to invalidate the caches on the finished.
correct thread.
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 # if self.after_callbacks is None, that means that whatever constructed the
# LoggingTransaction isn't expecting there to be any callbacks; assert that # LoggingTransaction isn't expecting there to be any callbacks; assert that
@ -254,6 +262,15 @@ class LoggingTransaction:
def call_on_exception( def call_on_exception(
self, callback: Callable[..., object], *args: Any, **kwargs: Any 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 # if self.exception_callbacks is None, that means that whatever constructed the
# LoggingTransaction isn't expecting there to be any callbacks; assert that # LoggingTransaction isn't expecting there to be any callbacks; assert that
# is not the case. # is not the case.