Add using and await using Declarations, SuppressedError, DisposableStack, and AsyncDisposableStack

[rbuckton]

This PR contains the Stage 3 specification text for Explicit Resource Management.

[rbuckton]

I'm not quite sure how to address the remaining esmeta issues.

[jmdyck]

Rather than suggest changes here, I've made a PR against this PR's branch: rbuckton#2

[rbuckton]

This last commit adds a few UpdateEmpty calls that aren't strictly necessary, but esmeta doesn't quite understand what's happening without it. I also had to switch AO parameters typed : a function object to : an ECMAScript language value since IsCallable doesn't seem to act as a type guard.

[bakkot]

@rbuckton Sorry about that - esmeta is still a little imprecise. You should feel free to write the spec text you want and not worry about esmeta's errors, and we can update esmeta or the ignore file.

[rbuckton]

@rbuckton Sorry about that - esmeta is still a little imprecise. You should feel free to write the spec text you want and not worry about esmeta's errors, and we can update esmeta or the ignore file.

I replaced the UpdateEmpty calls with a few asserts that seem to be accurate. For example, in ForIn/OfBodyEvaluation, if status is abrupt going in to DisposeResources, it should still be abrupt on the way out. Likewise, ForBodyEvaluation won't return a normal completion for empty, so DisposeResources shouldn't produce one either.

[rbuckton]

Please note, I've created rbuckton#3 as a separate PR against this one containing the additional specification changes that would be necessary to support https://github.com/tc39/proposal-async-explicit-resource-management, should it advance to Stage 3.

[rbuckton]

I found an issue with the change in e4f2d05 to use an EE to restrict binding patterns, in that it results in an ambiguous parse of using[x] before the EE can be applied, which was not intended.

I've filed tc39/proposal-explicit-resource-management#152 against the proposal spec, and will update this PR in due time.

[rbuckton]

I found an issue with the change in e4f2d05 to use an EE to restrict binding patterns, in that it results in an ambiguous parse of using[x] before the EE can be applied, which was not intended.

I've filed tc39/proposal-explicit-resource-management#152 against the proposal spec, and will update this PR in due time.

tc39/proposal-explicit-resource-management#152 has merged, and I've amended this PR to match as part of 3044fd9.

[rbuckton]

This now includes the await using declaration and AsyncDisposableStack, per prior consensus (incl. the March 2023 plenary).

[rbuckton]

Note to implementers: There is a typo in GetDisposeMethod that will be addressed by tc39/proposal-explicit-resource-management#217. The typo was introduced as part of a normative change that reached consensus in July 2023, but fixing it is also a potentially a normative change and may require additional consensus.

[rbuckton]

This is also missing the consensus change to use await using as the syntactic head for the asynchronous form of the using declaration. That will be up shortly.

[rbuckton]

25f1bc4 applies changes from the following PRs which previously achieved consensus in March 2023 and July 2023:

• Ignore return value of [Symbol.dispose]() method when hint is 'async-dispose' proposal-explicit-resource-management#180
• Move DisposeResources to Evaluation of FunctionStatementList proposal-explicit-resource-management#178
• Add missing calls to NewDisposeCapability AOs proposal-explicit-resource-management#175
• Correctly use hint in ForIn/OfBodyEvaluation proposal-explicit-resource-management#171
• Add missing .prototype property entries for DisposableStack/AsyncDisposableStack proposal-explicit-resource-management#167
• Merge async proposal back into sync proposal proposal-explicit-resource-management#154
• Revert 'await' restriction proposal-explicit-resource-management#153

[linusg]

Thanks for the changes, LGTM except for the explicit [[DisposableResourceStack]] unrooting in DisposeResources. There is precedent in 262 for informing implementors about collectable data structures, all in form of a NOTE step:

https://tc39.es/ecma262/#sec-%iteratorhelperprototype%.return

NOTE: Once a generator enters the completed state it never leaves it and its associated execution context is never resumed. Any execution state associated with obj can be discarded at this point.

https://tc39.es/ecma262/#sec-generatorstart

NOTE: Once a generator enters the completed state it never leaves it and its associated execution context is never resumed. Any execution state associated with acGenerator can be discarded at this point.

https://tc39.es/ecma262/#sec-generatorresumeabrupt

NOTE: Once a generator enters the completed state it never leaves it and its associated execution context is never resumed. Any execution state associated with generator can be discarded at this point.

I believe this is sufficiently clear and we should not assign values that are impossible to observe.

[rbuckton]

Thanks for the changes, LGTM except for the explicit [[DisposableResourceStack]] unrooting in DisposeResources. There is precedent in 262 for informing implementors about collectable data structures, all in form of a NOTE step:

I don't have a strong preference, though I'm wary of the hand-wavyness of just using a NOTE for a feature explicitly focused on resource/memory cleanup.

[michaelficarra]

@rbuckton I made a handy flowchart

[jmdyck]

Re Assert vs Note in the diagram: I'm not sure how I'd discern whether something is an invariant. My preference is that an Assert's condition should be something that, if you were working out an example and got to that step, you could actually check and confirm its truth at that point. (So, e.g., a statement about the future should be a Note, not an Assert.)

[michaelficarra]

@jmdyck The point was just that "you have an opportunity to do cleanup here" is definitely not an invariant, and it also doesn't impose a normative requirement, so it's either fluff or it's a note.

[jmdyck]

You should add type="built-in function" for

• sec-suppressederror
• sec-iterator.prototype-%symbol.dispose%
• sec-%asynciteratorprototype%-%symbol.asyncdispose%
• sec-disposablestack
• sec-disposablestack.prototype.adopt
• sec-disposablestack.prototype.defer
• sec-disposablestack.prototype.dispose
• sec-get-disposablestack.prototype.disposed
• sec-disposablestack.prototype.move
• sec-disposablestack.prototype.use
• sec-asyncdisposablestack
• sec-asyncdisposablestack.prototype.adopt
• sec-asyncdisposablestack.prototype.defer
• sec-asyncdisposablestack.prototype.disposeAsync
• sec-get-asyncdisposablestack.prototype.disposed
• sec-asyncdisposablestack.prototype.move
• sec-asyncdisposablestack.prototype.use

(I had a commit to do this, but there was a rebase problem.)

[jmdyck]

I suggest changing "This function" to "This method" for:

• sec-iterator.prototype-%symbol.dispose%
• sec-iterator.prototype-%symbol.iterator%
• sec-%asynciteratorprototype%-%symbol.asyncdispose%
• sec-%asynciteratorprototype%-%symbol.asynciterator%