Changes to Rule S9.1

[nobugs-hare]

Current Rule S9.1 looks a bit too restrictive; in particular, it would require co_await on functions such as response.end() - which is not really necessary. So, the aim of this issue is to:

• preserve the rule "IF THERE CAN BE A SUDDEN STATE CHANGE WITHIN A FUNCTION CALL - THERE MUST BE AN EXPLICIT MARKER OF IT IN THE USER CODE"
  • current S9.1 satisfies this (in this case marker is co_await itself), but it is sometimes too restrictive
• allow calling coroutines which CANNOT cause sudden state change, without co_await
  • one example of such a function is response.end()

Proposed way to implement the aims above:

1. allow to mark function calls (invocations) with [[nodecpp::no_await]] - (i.e. it can be EITHER co_await f() OR [[nodecpp::no_await]] f()).
2. allow to mark function declarations with [[nodecpp::no_await]]; this MUST be allowed ONLY in "our" code (NOT in user code); such functions can be called as simply f()
   A. We MUST NOT declare ANY coroutines which use co_await inside, as [[nodecpp::no_await]]
   B. OTOH, ANY function which ONLY causes starting an async operation, and without ANY co_awaits inside, is safe to be marked as [[nodecpp::no_await]]. This includes response.end()

IMPORTANT: Implementing this issue REQUIRES changing STATIC-CHECKS.md accordingly

[marcosbracco]

Some gotcha with [[nodecpp::no_await]] is that co_await is an expression, and can be used inside subexpressions (something that on itself is problematic because of references in-flight), but expressions can't have attributes. However statements can have attributes, and as long as [[nodecpp::no_await]] is used with void awaitables only the result looks the same.

nodecpp::awaitable<void> await_function();
[[nodecpp::no_await]] nodecpp::awaitable<void> no_await_function();

void f() {
	co_await await_function();
	[[nodecpp::no_await]] no_await_function();
}

So, the proposed text to [[Rule S9]] below (current [Rule S9.2] support StringLiteral class will be renumbered to [Rule S11]):

• [Rule S9] nodecpp::awaitable<>/co_await consistency (necessary to prevent leaks). Corroutines must return nodecpp::awaitable<> only.
  • [Rule S9.1] For any function f, ALL return values of ALL functions/coroutines returning nodecpp::awaitable<> and NOT having [[nodecpp::no_await]] at their declaration, MUST be fed to co_await operator within the same function f, and without any conversions. In addition, such return values MUST NOT be copied, nor passsed to other functions (except for special function wait_for_all()).
    • TEST CASES/PROHIBIT: af();, { auto x = af(); }, int x = af();, auto x = af(); anothre_f(x); /* where another_f() takes nodecpp::awaitable<> */, auto x = af(); auto y = x;
    • TEST CASES/ALLOW: co_await af();, int x = co_await af();, auto x = af(); auto y = af2(); co_await x; co_await y;, nodecpp::awaitable<int> x = af(); co_await x;, co_await wait_for_all(af(), af2())
  • [Rule S9.2] All calls to library functions returning nodecpp::awaitable<> that DO have attribute [[nodecpp::no_await]] at their declaration can be either optionally fed to co_await operator or marked with [[nodecpp::no_await]] at caller side.
    • TEST CASES/PROHIBIT: naf();, [[nodecpp::no_await]] af();
    • TEST CASES/ALLOW: co_await naf();, [[nodecpp::no_await]] naf();
  • [Rule S9.3] Prohibit using co_await inside subexpression or at other places than root statement expression or root variable initializer.
    • TEST CASES/PROHIBIT: int j = (co_await af()) + 1;, if(co_await af()) { ... };
    • TEST CASES/ALLOW: int i = co_await af();, co_await af();

[nobugs-hare]

As stated, Rule S9.2 (and its test cases) looks wrong. The whole idea of relaxing rules under this issue was to allow calls to naf(); (in particular, to response.end() in samples) without any attribution at the point of call.

[marcosbracco]

@nobugs-hare please review update to Rule S9.2 in the comment above.

[nobugs-hare]

IMO Looks good.