Add mutation explainer

[legendecas]

Compare run and set semantic (@@enter and @@dispose), and an example that could potentially be implemented on AsyncContext with set semantic:

async function doWork() {
  using parent = tracer.startAsCurrentSpan("parent");
  // do some work that 'parent' tracks
  console.log("doing some work...");
  // Create a nested span to track nested work
  {
    using child = tracer.startAsCurrentSpan("child");
    // do some work that 'child' tracks
    console.log("doing some nested work...")
    // the nested span is closed when it's out of scope
  }
  // This parent span is also closed when it goes out of scope
}

[Qard]

This mostly matches my thinking on the subject, though there's some nuance missing in how scopes apply within inner functions:

• Does the value remain the same in nested sync calls?
• Does the scope propagate as context does so async continuations can also set values that feed forward from that point in the context?

By providing implicit scopes we would mostly eliminate the need for user-provided scopes and could simply forward-propagate the values of any set calls to subsequent execution. It also flows much more naturally into flow-through semantics and provides for a more friendly interface to supporting multiple flow styles as you no longer need separate variables, you can just have separate setters that specify the flow for the value given at that point. (Actually, you can do the same with .run(...) too, but the semantics are more awkward given how the scoping of it suggests that values should not flow out.

[Qard]

My expectation would be that top-level would have an implicit scope so there should never be a point where store.set(...) can throw. This is also a requirement for solving the top-level configuration sharing problem Matteo described.

Rather, I would want for this AsyncContext.contextScope(...) thing to be an option for a user to provide additional scopes when they want ones more narrow than the runtime already provides. The runtime-provided scopes I'm thinking of would be module/script top-level and async functions. I believe everything else could just inherit the scope as it inherits context.

[Qard]

This sort of scenario is why I keep bringing up flow-through semantics. If context flows out of the return of that async function into subsequent execution then this interface is no longer needed.

[Qard]

Layering over unaltered AsyncContext would certainly not work, but patching snapshot retrieval can do this.

[Flarna]

I don't see the benefit of a contextScope.run(). If one is willing to add a new function for scoping the existing run should be ok already.
I'm also not sure if nesting of contextScopes across works as expected if it crosses library boundaries where the inner library might call back to the caller.
To my understanding a contextScope effects all variables so adding an inner scope might break a mutation for the other.

function foo(cb) {
  AsyncContext.contextScope(() => {
    // do some stuff
   cb(); // call the callback which mutates asyncVar
   // do some other stuff
  });
}

function bar() {
  AsyncContext.contextScope(() => {
    asyncVar.set("1");
    foo(() => { asyncVar.set("2") };  // this mutation would be "lost"
    asyncVar.get() // "1"
  });
}

[Flarna]

Allowing a @@enter without @@dispose opens the door for leaks. Either by forgetting @@dispose or calling them in the wrong order.
In my opinion the major benefit of a scoped set is gone because of this.

[legendecas]

@@enter and @@dispose are expected to be used with using declaration. Allowing it to be invoked manually is primarily for library extension, and shown in example below that compositing active spans with the context variables.

[Flarna]

As long as they are used correct in objects which are again intended for use with using and as a result the correct nesting is kept it should be fine.
If it is easy to mix up sequence of @@dispose it's quite problematic.

[shicks]

FWIW, I have a proof-of-concept for implementing aroundEach in Jasmine in userland entirely in terms of beforeEach and afterEach, though it relies on the legacy done style of async tests, so it wouldn't work in a more modern test framework that doesn't expose that.