2023-05-02 08:52:44 -06:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Cancellation - Synapse< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "../../favicon.svg" >
< link rel = "shortcut icon" href = "../../favicon.png" >
< link rel = "stylesheet" href = "../../css/variables.css" >
< link rel = "stylesheet" href = "../../css/general.css" >
< link rel = "stylesheet" href = "../../css/chrome.css" >
< link rel = "stylesheet" href = "../../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "../../highlight.css" >
< link rel = "stylesheet" href = "../../tomorrow-night.css" >
< link rel = "stylesheet" href = "../../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< link rel = "stylesheet" href = "../../docs/website_files/table-of-contents.css" >
< link rel = "stylesheet" href = "../../docs/website_files/remove-nav-buttons.css" >
< link rel = "stylesheet" href = "../../docs/website_files/indent-section-headers.css" >
2023-12-11 07:54:21 -07:00
< link rel = "stylesheet" href = "../../docs/website_files/version-picker.css" >
2023-05-02 08:52:44 -06:00
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "../../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2023-05-02 09:14:30 -06:00
< ol class = "chapter" > < li class = "chapter-item expanded affix " > < li class = "part-title" > Introduction< / li > < li class = "chapter-item expanded " > < a href = "../../welcome_and_overview.html" > Welcome and Overview< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Setup< / li > < li class = "chapter-item expanded " > < a href = "../../setup/installation.html" > Installation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../postgres.html" > Using Postgres< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../reverse_proxy.html" > Configuring a Reverse Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../setup/forward_proxy.html" > Configuring a Forward/Outbound Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../turn-howto.html" > Configuring a Turn Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../setup/turn/coturn.html" > coturn TURN server< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../setup/turn/eturnal.html" > eturnal TURN server< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../../delegate.html" > Delegation< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Upgrading< / li > < li class = "chapter-item expanded " > < a href = "../../upgrade.html" > Upgrading between Synapse Versions< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Usage< / li > < li class = "chapter-item expanded " > < a href = "../../federate.html" > Federation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/index.html" > Configuration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/config_documentation.html" > Configuration Manual< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/homeserver_sample_config.html" > Homeserver Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/logging_sample_config.html" > Logging Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../structured_logging.html" > Structured Logging< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../templates.html" > Templates< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/user_authentication/index.html" > User Authentication< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/user_authentication/single_sign_on/index.html" > Single-Sign On< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../openid.html" > OpenID Connect< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/user_authentication/single_sign_on/saml.html" > SAML< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/user_authentication/single_sign_on/cas.html" > CAS< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../sso_mapping_providers.html" > SSO Mapping Providers< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../../password_auth_providers.html" > Password Auth Providers< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../jwt.html" > JSON Web Tokens< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../usage/configuration/user_authentication/refresh_tokens.html" > Refresh Tokens< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../../CAPTCHA_SETUP.html" > Registration Captcha< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../application_services.html" > Application Services< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../server_notices.html" > Server Notices< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../consent_tracking.html" > Consent Tracking< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../user_directory.html" > User Directory< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../message_retention_policies.html" > Message Retention Policies< / a > < / li > < li class = "chapter-item expanded " > < a href = "../../modules/index.html" > Pluggable Modules< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../modules/writ
2023-05-02 08:52:44 -06:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
2023-12-11 07:54:21 -07:00
< div class = "version-picker" >
< div class = "dropdown" >
< div class = "select" >
< span > < / span >
< i class = "fa fa-chevron-down" > < / i >
< / div >
< input type = "hidden" name = "version" >
< ul class = "dropdown-menu" >
<!-- Versions will be added dynamically in version - picker.js -->
< / ul >
< / div >
< / div >
2023-05-02 08:52:44 -06:00
< / div >
< h1 class = "menu-title" > Synapse< / h1 >
< div class = "right-buttons" >
< a href = "../../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse" title = "Git repository" aria-label = "Git repository" >
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
< a href = "https://github.com/matrix-org/synapse/edit/develop/docs/development/synapse_architecture/cancellation.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- Page table of contents -->
< div class = "sidetoc" >
< nav class = "pagetoc" > < / nav >
< / div >
< h1 id = "cancellation" > < a class = "header" href = "#cancellation" > Cancellation< / a > < / h1 >
< p > Sometimes, requests take a long time to service and clients disconnect
before Synapse produces a response. To avoid wasting resources, Synapse
can cancel request processing for select endpoints marked with the
< code > @cancellable< / code > decorator.< / p >
< p > Synapse makes use of Twisted's < code > Deferred.cancel()< / code > feature to make
cancellation work. The < code > @cancellable< / code > decorator does nothing by itself
and merely acts as a flag, signalling to developers and other code alike
that a method can be cancelled.< / p >
< h2 id = "enabling-cancellation-for-an-endpoint" > < a class = "header" href = "#enabling-cancellation-for-an-endpoint" > Enabling cancellation for an endpoint< / a > < / h2 >
< ol >
< li > Check that the endpoint method, and any < code > async< / code > functions in its call
tree handle cancellation correctly. See
< a href = "#handling-cancellation-correctly" > Handling cancellation correctly< / a >
for a list of things to look out for.< / li >
< li > Add the < code > @cancellable< / code > decorator to the < code > on_GET/POST/PUT/DELETE< / code >
method. It's not recommended to make non-< code > GET< / code > methods cancellable,
since cancellation midway through some database updates is less
likely to be handled correctly.< / li >
< / ol >
< h2 id = "mechanics" > < a class = "header" href = "#mechanics" > Mechanics< / a > < / h2 >
< p > There are two stages to cancellation: downward propagation of a
< code > cancel()< / code > call, followed by upwards propagation of a < code > CancelledError< / code >
out of a blocked < code > await< / code > .
Both Twisted and asyncio have a cancellation mechanism.< / p >
< table > < thead > < tr > < th > < / th > < th > Method< / th > < th > Exception< / th > < th > Exception inherits from< / th > < / tr > < / thead > < tbody >
< tr > < td > Twisted< / td > < td > < code > Deferred.cancel()< / code > < / td > < td > < code > twisted.internet.defer.CancelledError< / code > < / td > < td > < code > Exception< / code > (!)< / td > < / tr >
< tr > < td > asyncio< / td > < td > < code > Task.cancel()< / code > < / td > < td > < code > asyncio.CancelledError< / code > < / td > < td > < code > BaseException< / code > < / td > < / tr >
< / tbody > < / table >
< h3 id = "deferredcancel" > < a class = "header" href = "#deferredcancel" > Deferred.cancel()< / a > < / h3 >
< p > When Synapse starts handling a request, it runs the async method
responsible for handling it using < code > defer.ensureDeferred< / code > , which returns
a < code > Deferred< / code > . For example:< / p >
< pre > < code class = "language-python" > def do_something() -> Deferred[None]:
...
@cancellable
async def on_GET() -> Tuple[int, JsonDict]:
d = make_deferred_yieldable(do_something())
await d
return 200, {}
request = defer.ensureDeferred(on_GET())
< / code > < / pre >
< p > When a client disconnects early, Synapse checks for the presence of the
< code > @cancellable< / code > decorator on < code > on_GET< / code > . Since < code > on_GET< / code > is cancellable,
< code > Deferred.cancel()< / code > is called on the < code > Deferred< / code > from
< code > defer.ensureDeferred< / code > , ie. < code > request< / code > . Twisted knows which < code > Deferred< / code >
< code > request< / code > is waiting on and passes the < code > cancel()< / code > call on to < code > d< / code > .< / p >
< p > The < code > Deferred< / code > being waited on, < code > d< / code > , may have its own handling for
< code > cancel()< / code > and pass the call on to other < code > Deferred< / code > s.< / p >
< p > Eventually, a < code > Deferred< / code > handles the < code > cancel()< / code > call by resolving itself
with a < code > CancelledError< / code > .< / p >
< h3 id = "cancellederror" > < a class = "header" href = "#cancellederror" > CancelledError< / a > < / h3 >
< p > The < code > CancelledError< / code > gets raised out of the < code > await< / code > and bubbles up, as
per normal Python exception handling.< / p >
< h2 id = "handling-cancellation-correctly" > < a class = "header" href = "#handling-cancellation-correctly" > Handling cancellation correctly< / a > < / h2 >
< p > In general, when writing code that might be subject to cancellation, two
things must be considered:< / p >
< ul >
< li > The effect of < code > CancelledError< / code > s raised out of < code > await< / code > s.< / li >
< li > The effect of < code > Deferred< / code > s being < code > cancel()< / code > ed.< / li >
< / ul >
< p > Examples of code that handles cancellation incorrectly include:< / p >
< ul >
< li > < code > try-except< / code > blocks which swallow < code > CancelledError< / code > s.< / li >
< li > Code that shares the same < code > Deferred< / code > , which may be cancelled, between
multiple requests.< / li >
< li > Code that starts some processing that's exempt from cancellation, but
uses a logging context from cancellable code. The logging context
will be finished upon cancellation, while the uncancelled processing
is still using it.< / li >
< / ul >
< p > Some common patterns are listed below in more detail.< / p >
< h3 id = "async-function-calls" > < a class = "header" href = "#async-function-calls" > < code > async< / code > function calls< / a > < / h3 >
< p > Most functions in Synapse are relatively straightforward from a
cancellation standpoint: they don't do anything with < code > Deferred< / code > s and
purely call and < code > await< / code > other < code > async< / code > functions.< / p >
< p > An < code > async< / code > function handles cancellation correctly if its own code
handles cancellation correctly and all the async function it calls
handle cancellation correctly. For example:< / p >
< pre > < code class = "language-python" > async def do_two_things() -> None:
check_something()
await do_something()
await do_something_else()
< / code > < / pre >
< p > < code > do_two_things< / code > handles cancellation correctly if < code > do_something< / code > and
< code > do_something_else< / code > handle cancellation correctly.< / p >
< p > That is, when checking whether a function handles cancellation
correctly, its implementation and all its < code > async< / code > function calls need to
be checked, recursively.< / p >
< p > As < code > check_something< / code > is not < code > async< / code > , it does not need to be checked.< / p >
< h3 id = "cancellederrors" > < a class = "header" href = "#cancellederrors" > CancelledErrors< / a > < / h3 >
< p > Because Twisted's < code > CancelledError< / code > s are < code > Exception< / code > s, it's easy to
accidentally catch and suppress them. Care must be taken to ensure that
< code > CancelledError< / code > s are allowed to propagate upwards.< / p >
< table width = "100%" >
< tr >
< td width = "50%" valign = "top" >
< p > < strong > Bad< / strong > :< / p >
< pre > < code class = "language-python" > try:
await do_something()
except Exception:
# `CancelledError` gets swallowed here.
logger.info(...)
< / code > < / pre >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > try:
await do_something()
except CancelledError:
raise
except Exception:
logger.info(...)
< / code > < / pre >
< / td >
< / tr >
< tr >
< td width = "50%" valign = "top" >
< p > < strong > OK< / strong > :< / p >
< pre > < code class = "language-python" > try:
check_something()
# A `CancelledError` won't ever be raised here.
except Exception:
logger.info(...)
< / code > < / pre >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > try:
await do_something()
except ValueError:
logger.info(...)
< / code > < / pre >
< / td >
< / tr >
< / table >
< h4 id = "defergatherresults" > < a class = "header" href = "#defergatherresults" > defer.gatherResults< / a > < / h4 >
< p > < code > defer.gatherResults< / code > produces a < code > Deferred< / code > which:< / p >
< ul >
< li > broadcasts < code > cancel()< / code > calls to every < code > Deferred< / code > being waited on.< / li >
< li > wraps the first exception it sees in a < code > FirstError< / code > .< / li >
< / ul >
< p > Together, this means that < code > CancelledError< / code > s will be wrapped in
a < code > FirstError< / code > unless unwrapped. Such < code > FirstError< / code > s are liable to be
swallowed, so they must be unwrapped.< / p >
< table width = "100%" >
< tr >
< td width = "50%" valign = "top" >
< p > < strong > Bad< / strong > :< / p >
< pre > < code class = "language-python" > async def do_something() -> None:
await make_deferred_yieldable(
defer.gatherResults([...], consumeErrors=True)
)
try:
await do_something()
except CancelledError:
raise
except Exception:
# `FirstError(CancelledError)` gets swallowed here.
logger.info(...)
< / code > < / pre >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > async def do_something() -> None:
await make_deferred_yieldable(
defer.gatherResults([...], consumeErrors=True)
).addErrback(unwrapFirstError)
try:
await do_something()
except CancelledError:
raise
except Exception:
logger.info(...)
< / code > < / pre >
< / td >
< / tr >
< / table >
< h3 id = "creation-of-deferreds" > < a class = "header" href = "#creation-of-deferreds" > Creation of < code > Deferred< / code > s< / a > < / h3 >
< p > If a function creates a < code > Deferred< / code > , the effect of cancelling it must be considered. < code > Deferred< / code > s that get shared are likely to have unintended behaviour when cancelled.< / p >
< table width = "100%" >
< tr >
< td width = "50%" valign = "top" >
< p > < strong > Bad< / strong > :< / p >
< pre > < code class = "language-python" > cache: Dict[str, Deferred[None]] = {}
def wait_for_room(room_id: str) -> Deferred[None]:
deferred = cache.get(room_id)
if deferred is None:
deferred = Deferred()
cache[room_id] = deferred
# `deferred` can have multiple waiters.
# All of them will observe a `CancelledError`
# if any one of them is cancelled.
return make_deferred_yieldable(deferred)
# Request 1
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
# Request 2
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
< / code > < / pre >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > cache: Dict[str, Deferred[None]] = {}
def wait_for_room(room_id: str) -> Deferred[None]:
deferred = cache.get(room_id)
if deferred is None:
deferred = Deferred()
cache[room_id] = deferred
# `deferred` will never be cancelled now.
# A `CancelledError` will still come out of
# the `await`.
# `delay_cancellation` may also be used.
return make_deferred_yieldable(stop_cancellation(deferred))
# Request 1
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
# Request 2
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
< / code > < / pre >
< / td >
< / tr >
< tr >
< td width = "50%" valign = "top" >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > cache: Dict[str, List[Deferred[None]]] = {}
def wait_for_room(room_id: str) -> Deferred[None]:
if room_id not in cache:
cache[room_id] = []
# Each request gets its own `Deferred` to wait on.
deferred = Deferred()
cache[room_id]].append(deferred)
return make_deferred_yieldable(deferred)
# Request 1
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
# Request 2
await wait_for_room(" !aAAaaAaaaAAAaAaAA:matrix.org" )
< / code > < / pre >
< / td >
< / table >
< h3 id = "uncancelled-processing" > < a class = "header" href = "#uncancelled-processing" > Uncancelled processing< / a > < / h3 >
< p > Some < code > async< / code > functions may kick off some < code > async< / code > processing which is
intentionally protected from cancellation, by < code > stop_cancellation< / code > or
other means. If the < code > async< / code > processing inherits the logcontext of the
request which initiated it, care must be taken to ensure that the
logcontext is not finished before the < code > async< / code > processing completes.< / p >
< table width = "100%" >
< tr >
< td width = "50%" valign = "top" >
< p > < strong > Bad< / strong > :< / p >
< pre > < code class = "language-python" > cache: Optional[ObservableDeferred[None]] = None
async def do_something_else(
to_resolve: Deferred[None]
) -> None:
await ...
logger.info(" done!" )
to_resolve.callback(None)
async def do_something() -> None:
if not cache:
to_resolve = Deferred()
cache = ObservableDeferred(to_resolve)
# `do_something_else` will never be cancelled and
# can outlive the `request-1` logging context.
run_in_background(do_something_else, to_resolve)
await make_deferred_yieldable(cache.observe())
with LoggingContext(" request-1" ):
await do_something()
< / code > < / pre >
< / td >
< td width = "50%" valign = "top" >
< p > < strong > Good< / strong > :< / p >
< pre > < code class = "language-python" > cache: Optional[ObservableDeferred[None]] = None
async def do_something_else(
to_resolve: Deferred[None]
) -> None:
await ...
logger.info(" done!" )
to_resolve.callback(None)
async def do_something() -> None:
if not cache:
to_resolve = Deferred()
cache = ObservableDeferred(to_resolve)
run_in_background(do_something_else, to_resolve)
# We'll wait until `do_something_else` is
# done before raising a `CancelledError`.
await make_deferred_yieldable(
delay_cancellation(cache.observe())
)
else:
await make_deferred_yieldable(cache.observe())
with LoggingContext(" request-1" ):
await do_something()
< / code > < / pre >
< / td >
< / tr >
< tr >
< td width = "50%" >
< p > < strong > OK< / strong > :< / p >
< pre > < code class = "language-python" > cache: Optional[ObservableDeferred[None]] = None
async def do_something_else(
to_resolve: Deferred[None]
) -> None:
await ...
logger.info(" done!" )
to_resolve.callback(None)
async def do_something() -> None:
if not cache:
to_resolve = Deferred()
cache = ObservableDeferred(to_resolve)
# `do_something_else` will get its own independent
# logging context. `request-1` will not count any
# metrics from `do_something_else`.
run_as_background_process(
" do_something_else" ,
do_something_else,
to_resolve,
)
await make_deferred_yieldable(cache.observe())
with LoggingContext(" request-1" ):
await do_something()
< / code > < / pre >
< / td >
< td width = "50%" >
< / td >
< / tr >
< / table >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../../development/dependencies.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../../log_contexts.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "../../development/dependencies.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../../log_contexts.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "../../elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../../mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../../searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../../clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../../highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../../book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" src = "../../docs/website_files/table-of-contents.js" > < / script >
2023-12-11 07:54:21 -07:00
< script type = "text/javascript" src = "../../docs/website_files/version-picker.js" > < / script >
< script type = "text/javascript" src = "../../docs/website_files/version.js" > < / script >
2023-05-02 08:52:44 -06:00
< / body >
2023-12-11 07:54:21 -07:00
< / html >
