Propagate @async Annotation Upwards with Coroutine-based Async Functions

[findstr]

Background

In Lua, asynchronous operations are often handled via coroutines (e.g., using coroutine.yield). When one function calls another asynchronous function that uses coroutine, the calling function is inherently asynchronous as well, because the execution of the calling function is paused and resumed once the asynchronous operation completes.

However, currently, the @async annotation does not propagate upwards. This means that if a function calls an asynchronous function (e.g., using coroutine.yield or returning a Promise), the calling function needs to be manually marked as @async in order to ensure that the asynchronous nature is captured correctly. It would be great if this could be automated.

Proposal

If a function calls another function that is marked as @async and uses coroutines (or similar async patterns), the calling function should automatically inherit the @async annotation, similar to how asynchronous behavior is propagated in many other languages (e.g., TypeScript).

This would reduce the need for redundant annotations and help maintain consistency in larger codebases where multiple functions are asynchronous and rely on coroutines for concurrency.

Benefits

Consistency: Functions that use async functions (e.g., fetchData) should automatically inherit the @async annotation to prevent forgetting to annotate dependent functions.
Reduced Boilerplate: This feature would reduce the need for redundant annotations, especially in large codebases with many interdependent asynchronous functions.
Improved Developer Experience: Automatic propagation would improve the development workflow, ensuring that async functions are correctly marked without manual intervention.

[tomlau10]

I think your suggestion will break the await-in-sync diagnostic checking logic. 😕
According to the description, this is triggered when calling an asynchronous function from within a synchronous function.
(You have to enable this check group first as it is disabled by default)

• luarc.json

{
    "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
    "diagnostics.groupFileStatus": {
        "await": "Any"
    }
}

• test.lua

---@async
local function async() end

local function dont_want_async()
    async() --> warning: Async function can only be called in async function.Lua Diagnostics.(await-in-sync)
end

---

If @async annotations are propagated upwards to its caller, then nothing can be checked against?
(as the caller now become @async as well)
And sometimes we just generally don't want functions to become async, for example to avoid reentrancy issues 🤔.
If a function is async, it may need special handlings to prevent race conditions,, and only after developer thought it is handled correctly we then manually mark it as @async ?

[findstr]

Thank you very much for your reply.

I am using Lua to develop a server for a large game.

The server framework wraps asynchronous operations such as network links, RPC, and database access in coroutine.

I can use await-in-sync diagnostic checking to add the ---@async annotation to all business logic.

Once the bottom-level function becomes non-async, due to its propagation, all places that call this function need to delete the @async annotation.

Although manual deletion is a bit of work, it is not a big problem.

The biggest problem is that await-in-sync diagnostic checking only has positive detection, so it is difficult for us to find which ---@async is useless.

Therefore, is it possible for us to annotate @async as "active async" or "passive async", so that at least when we modify the business logic, we can use await-in-sync diagnostic checking to correct all async annotations.

[tomlau10]

is it possible for us to annotate @async as "active async" or "passive async"

I am not maintainer but just a contributor who fixed a couple of issues, and currently I have no further ideas on how to solve your use case properly 🙈

[findstr]

I know it's not polite to @sumneko, but do you have any solution to this problem?

Thank you very much。

[sumneko]

我觉得手动标记所有的异步比较好，异步是非常复杂的，在逐一标记的过程中会强迫你思考调用链上的每个函数是否会有重入问题，是否会阻塞不该阻塞的流程，回调函数是否会经过不支持让出的栈帧。

我目前也没有精力修改这方面的实现，如果你有强烈需求的话可以提PR。

[sumneko]

I think manually annotating all the asynchronous parts is better. Asynchronous operations are very complex, and manually annotating forces you to consider whether each function in the call chain might have reentrancy issues, whether it might block a process that shouldn't be blocked, and whether callback functions might pass through unsupported stack frames. I currently don't have the bandwidth to modify this implementation. If you strongly feel the need, you can submit a pull request (PR).