Async using syntax

[mhofman]

I've seen different syntax suggestions related to async disposal spread over different issues, in particular tc39/proposal-explicit-resource-management#16 tc39/proposal-explicit-resource-management#76 tc39/proposal-explicit-resource-management#84 #4. I wanted to concentrate the discussion in a single issue.

I'd first like to discuss the ongoing assumption that using an async-disposable requires specific syntax.
The way I model the using syntax is that a block containing a using declaration implicitly creates a DisposableStack. Every using declaration implicitly results in a .use() on the stack, and that exiting the block implicitly calls [Symbol.dispose]() on the stack.

Now if we assume that we have a concept of "async blocks", instead of a DisposableStack being implicitly created, it'd be an AsyncDisposableStack. At that point any using declaration would similarly call the .use() of the implicit async disposable stack, which is a synchronous operation, and it's the exit of the "async block" which awaits the [Symbol.asyncDispose]() call.

As such I would be against any syntax that uses the await keyword for the using declaration, as nothing is awaited at the declaration time. Similarly I would be against any syntax that doesn't use the await keyword on the block as a marker of interleaving. I would be ok with a async using declaration to be explicit, but I would consider that unnecessary verbosity.

Given the mental model above, I believe it would be entirely natural that for await (using r of ...), and using declarations inside for-await-of blocks in general, would implicitly use an AsyncDisposableStack. for-await-of is conceptually the only "async block" in the language at the moment. Then it become a matter of specifying what the syntax of an "async block" not tied to iteration looks like.

[mhofman]

Also I would like to clarify my position from the presentation.

If future syntax for async disposables will require an explicit async using marker, I am ok with the proposal continuing as-is with for-await-of loops invoking [Symbol.dispose]() for using declarations (whether in the for declaration or in the block), however we have to realize that we are permanently closing the door to not requiring the async marker.

[mhofman]

Thinking more about this, I believe that the top level block of an async function could also be considered as an "async block", at which point using declarations at the top level of async functions would similarly trigger @@asyncDispose before falling back to @@dispose.

[Jack-Works]

(please be aware of async do { stmt_list; } from do expression proposal)

[rbuckton]

I think having using support asyncDispose in an async function was previously discussed during a plenary several years ago. @erights has repeatedly contended that we must have some kind of marker denoting the implicit await. While I agree that an async function body is an obvious boundary, we would need some way to annotate a given block as containing this implicit await to satisfy this concern.

I've never been 100% convinced that such an annotation is strictly necessary. Synchronous using will have an effect on the surrounding block given that [Symbol.dispose] will now be called, so anyone employing using would need to be aware of this relationship. I feel that a similar expectation could be applied to an async function or generator: a block containing an await using in async code will not only call [Symbol.asyncDispose] but would also await its result. If we didn't have the requirement to syntactically document the containing block, I'd add await using back in a heartbeat.

That said, I don't think a plain using declaration should ever use [Symbol.asyncDispose] magically. Much of this proposal is about being intentional about how you track your resources: No destructuring in using, throwing on missing [Symbol.dispose] early, no DisposableStack.from(iterable) due to potential foot-guns, etc. I think being explicit about the kind of resource you are expecting to track is important.

Assuming we were to continue that explicitness guarantee, and could add something like await using, I'd expect the following scenarios:

for (using res of iterable) ...; // sync iteration, sync dispose
for (await using res of iterable) ..; // sync iteration, async dispose
for await (using res of asyncIterable) ...; // async iteration, sync dispose
for await (await using res of asyncIterable) ...; // async iteration, async dispose

I'm far more likely to drop support for using in for, for-of, and for-await-of than to have a using in for-await-of choose to use @@asyncDispose and break with how using works in other cases (especially given @bakkot's concern about for(using x = ...; ;) ...;).

I've previously mentioned that C# (from which the using and await using declarations were borrowed) does not require a block marker. IIRC, @erights contention to that was that C# is multi-threaded and thus any code could potentially be preempted (@erights, please correct me if I am mischaracterizing your argument), but I think it's perfectly reasonable to write C# code that can execute sequentially with async functions where such preempting doesn't occur, as well as to use a SynchronizationContext that schedules async completions on an event loop.

[rbuckton]

I also think that the fact we had to introduce for-await-of syntax itself is an indicator that we should be explicit and intentional. Having using magically support @@asyncDispose in an async function would be more akin to having for-of magically support @@asyncIterable in an async function. You have to opt-in to the async behavior with the await keyword, and I believe requiring the same explicit opt-in for using aligns with that premise.

[mhofman]

I would like to stress as explained above that await using declaration is a misnomer. I would be entirely opposed to having the await keyword on the declaration as there is no interleaving point at the declaration time.

Both @erights and I want to make sure the place where any interleaving happens is not surprising. In a for await of it's explicit that there is interleaving due to the iteration. An async function top level block would effectively have no interleaving since the async disposal happens after return or throw. However nested blocks cannot start introducing implicit interleaving points, which motivates our requirement for await marking the blocks themselves.

Given that AsyncDisposableStack.prototype.use first attempts to use asyncDispose, falling back to dispose, i do not find surprising that using would do the same. For most usages, it should be entirely unsurprising since authors can keep using a sync dispose resource in "async blocks". The only surprising part may be for authors trying to using an async dispose resource in a non-"async block", however that is something both static type checkers and exception at the declaration time will quickly prevent. All this is assuming resources would be either async or sync dispose, I don't see a valid use case for object that have both symbols with different behaviors.

[rbuckton]

Given that AsyncDisposableStack.prototype.use first attempts to use asyncDispose, falling back to dispose, i do not find surprising that using would do the same.

This still doesn't align with how for-of and for-await-of work in async functions. A for-of in an async function doesn't look for an @@asyncIterator, only for-await-of does. A using in a sync or async function should work the same way regardless (i.e., synchronous). A variation of using that looks for an @@asyncDispose first must be distinguishable from the synchronous version, whether that is via an await prefix or some other keyword. I feel await using is reasonable since it implies that an await occurs, just as a for-await-of implies an await occurs. I'd be fine with a different prefix keyword, if one can be found that is acceptable to all parties.

I don't see a valid use case for object that have both symbols with different behaviors.

While I don't disagree that objects shouldn't have both, a platform like NodeJS could reasonably have a [Symbol.dispose]() that blocks the main thread while closing a file stream (i.e., via fs.closeSync(fd)), and a [Symbol.asyncDispose]() that does the same thing asynchronously (i.e., via fs.close(fd, callback)). The caller could then choose whether to use the non-blocking version (via await using) or the blocking version (via using) based on their needs.

[erights]

(via await using)

As @mhofman has stated, this is the wrong place for the await to appear, because it is not where the interleaving would happen. However, that doesn't mean we cannot make this distinction. I suggest that we spell it as using async or async using. (I prefer the first but could live with either.) This is a perfect use of async -- it says beware of a possible await interleaving point elsewhere close by.

[ZachHaber]

For what it's worth, I think async using is preferable to me over await using since it makes it clear that it's async and not trying to await the result of the function called to create the resource. It also stays consistent with difference between sync vs async functions: async function vs function and async ()=>{} vs ()=>{}. using async would probably make it more readable as a sentence than async using does, but at the cost of having to remember that you stick async in a different location than with functions.

async function test(){
  // synchronous resource and disposal for comparison
  using sync = getSyncResource();
  // await using
  await using db = await getConnection();
  // await using implicitly awaits.
  await using db = getConnection();
  // async using
  async using db = await getConnection();
  // using async
  using async db = await getConnection();
}

I think I'd only prefer await using or using await if they implicitly awaited the right side expression. Which somewhat assumes that anything that needs an async disposal would be a Promise to start with and would mean that it would waste time awaiting values if the right side isn't a promise or has already been resolved earlier.

---

In regards to explicit block syntax for async disposal, I think that async {} aka async code block would work well for it. It is currently a syntax error, so it won't break anything, it adds the information at the top of the block for easier lexing and human understanding, and it remains consistent with meanings. The downside is: a basic async code block wouldn't really make sense on it's own without awaiting it, and so would require await keyword to make the syntax await async {}. There's also no way to shorten await async {} to await {} as await {} is valid syntax currently which awaits an object literal.

This concept would then combine well with proposals that make new styles of code blocks that have other functionalities: async do expressions and async pattern match enhancement both could be considered as a proper interleave point with an async disposal.

This does mean that if you use using inside of an async do block, and the return the value you ran using with, it would still get disposed and thus be invalid to return, and async match wouldn't allow using statements without combining it with async do as using appears to be a statement rather than an expression (assuming I have that terminology correct).

// async block
await async {
  async using db = await getConnection();
}

// async do block
async using toCleanup = await async do {
  // This `using` is inside the async do block, so it would get disposed properly
  using async pool = await getPool();
  // explicit return for clarity, as the syntax hasn't been fully nailed down yet
  // Note: no `using` here, since we want this to live until outside the do block.
  return await pool.getConnection();
}

At the very least, even without an explicit way to specify an async disposal block, any async block should be a candidate for async disposal. And then the disposal can just bubble up to the nearest async block, even if that ends up being the module itself (Top-level await in ESModules). This would also allow async IIFEs to be used for async disposal until there's other more terse ways to create an async block.

I feel that the async part of this proposal is more important to have in the language than the synchronous part since most file system support, databases, network, will ideally be async and require async cleanup to handle correctly, and without both parts being added together (or in short succession), I can see people just using the synchronous disposing for these and just swallowing the error (.catch(()=>{})) or logging it only to get the benefits of cleaner code.

The semantics of the async disposal would have to be different than sync disposal unless you have to specify that whatever block they are used in is an async block to allow them to work at all, which seems limiting and confusing, OR all blocks in async code will allow for async disposal regardless, which is problematic due to the implicit interleaving that that creates.

[rbuckton]

(via await using)

As @mhofman has stated, this is the wrong place for the await to appear, because it is not where the interleaving would happen. However, that doesn't mean we cannot make this distinction. I suggest that we spell it as using async or async using. (I prefer the first but could live with either.) This is a perfect use of async -- it says beware of a possible await interleaving point elsewhere close by.

I am leaning toward async using so it isn't confused with using async = where async is a regular identifier.

@erights, do you still have reservations about not having an explicit await marker? Would the fact that an async function itself is annotated with an async keyword not be enough of an indication, along with the fact that async using declarations themselves are annotated with an async keyword? Would banning async using at the top level of a module help (even though top-level await is still valid)?

If so, I will continue with my plan to postpone async using to a follow-on proposal, though it would be nice to move forward with async using at the upcoming plenary if we can find a compromise.

[mhofman]

I believe async using should only be valid at the top level of an async function and at the top level for-await-of block, but not other places since those wouldn't already be understood to have interleaving points on scope exit.

As I mentioned, I'm still not sure the explicit async marker on using is necessary. IMO it's the kind of scope (async function / for-await-of) that implies the async nature of the dispose stack, and using is syntactic sugar for the stack.use() method.

[bakkot]

but not other places since those wouldn't already be understood to have interleaving points on scope exit.

I suspect that very, very few people are aware that the end of a for-await-of loop is an interleaving point, and I don't think that's actually caused many problems in practice. So I personally don't think that restriction makes sense.