Debian Codegraph @

clang-tools-extra/docs/clang-tidy/checks/misc/coroutine-hostile-raii.rst

raw
1 .. title:: clang-tidy - misc-coroutine-hostile-raii
2
3 misc-coroutine-hostile-raii
4 ===========================
5
6 Detects when objects of certain hostile RAII types persists across suspension
7 points in a coroutine. Such hostile types include scoped-lockable types and
8 types belonging to a configurable denylist.
9
10 Some objects require that they be destroyed on the same thread that created them.
11 Traditionally this requirement was often phrased as "must be a local variable",
12 under the assumption that local variables always work this way. However this is
13 incorrect with C++20 coroutines, since an intervening ``co_await`` may cause the
14 coroutine to suspend and later be resumed on another thread.
15
16 The lifetime of an object that requires being destroyed on the same thread must
17 not encompass a ``co_await`` or ``co_yield`` point. If you create/destroy an object,
18 you must do so without allowing the coroutine to suspend in the meantime.
19
20 Following types are considered as hostile:
21
22 - Scoped-lockable types: A scoped-lockable object persisting across a suspension
23 point is problematic as the lock held by this object could be unlocked by a
24 different thread. This would be undefined behaviour.
25 This includes all types annotated with the ``scoped_lockable`` attribute.
26
27 - Types belonging to a configurable denylist.
28
29 .. code-block:: c++
30
31 // Call some async API while holding a lock.
32 task coro() {
33 const std::lock_guard l(&mu_);
34
35 // Oops! The async Bar function may finish on a different
36 // thread from the one that created the lock_guard (and called
37 // Mutex::Lock). After suspension, Mutex::Unlock will be called on the wrong thread.
38 co_await Bar();
39 }
40
41 Options
42 -------
43
44 .. option:: RAIITypesList
45
46 A semicolon-separated list of qualified types which should not be allowed to
47 persist across suspension points.
48 Eg: ``my::lockable; a::b;::my::other::lockable;``
49 The default value of this option is `"std::lock_guard;std::scoped_lock"`.
50
51 .. option:: AllowedAwaitablesList
52
53 A semicolon-separated list of qualified types of awaitables types which can
54 be safely awaited while having hostile RAII objects in scope.
55
56 ``co_await``-ing an expression of ``awaitable`` type is considered
57 safe if the ``awaitable`` type is part of this list.
58 RAII objects persisting across such a ``co_await`` expression are
59 considered safe and hence are not flagged.
60
61 Example usage:
62
63 .. code-block:: c++
64
65 // Consider option AllowedAwaitablesList = "safe_awaitable"
66 struct safe_awaitable {
67 bool await_ready() noexcept { return false; }
68 void await_suspend(std::coroutine_handle<>) noexcept {}
69 void await_resume() noexcept {}
70 };
71 auto wait() { return safe_awaitable{}; }
72
73 task coro() {
74 // This persists across both the co_await's but is not flagged
75 // because the awaitable is considered safe to await on.
76 const std::lock_guard l(&mu_);
77 co_await safe_awaitable{};
78 co_await wait();
79 }
80
81 Eg: ``my::safe::awaitable;other::awaitable``
82 The default value of this option is empty string `""`.
83