Microsoft.Extensions.AsyncState readme suggestions

[KalleOlaviNiemitalo]

Suggestions for things that could be added to src/Libraries/Microsoft.Extensions.AsyncState/README.md:

• Why would one use this library instead of static AsyncLocal<T>? There seem to be the following reasons:
  • The lifetime of values is explicitly controlled; if you call an async function that sets a value, the caller can also access this value. With AsyncLocal<T>, values propagate only to called functions and not to callers of async functions, although you can change that by making the caller set up a holder object and mutating that in the called function.
  • Minimizes the number of async locals in the ExecutionContext, making it cheaper to copy (e.g. during ILogger.BeginScope).
  • Can explicitly reset the state and ensure that the values are no longer rooted by ExecutionContext in any long-lived task.
  • Can use the Microsoft.AspNetCore.AsyncState package to tie the lifetime of values to HttpContext, without the code that uses IAsyncContext<T> directly depending on ASP.NET Core.
• When to call IAsyncState.Initialize() and IAsyncState.Reset(). The default implementation of IAsyncContext<T> will throw if IAsyncState.Initialize has not been called, but the library itself never calls that.

[Tratcher]

@geeknoid I can update the readme, but who knows the actual answers to these questions?

[geeknoid]

@Tratcher Unfortunately, the few guys we had working on this stuff left the company a while ago. I think @davidfowl and @tekian likely know what's what.

[geeknoid]

Internally, there's also some R9 docs here: https://eng.ms/docs/experiences-devices/r9-sdk/docs/http-processing/asynchronous-state

[KalleOlaviNiemitalo]

Minimizes the number of async locals in the ExecutionContext, making it cheaper to copy (e.g. during ILogger.BeginScope).

Also, when there is a large number of async values linked to the same ExecutionContext, reading them may be faster via this library than if there were a separate AsyncLocal<T> instance for each, because the library can use the precomputed AsyncStateToken.Index as an array index, instead of ManyElementAsyncLocalValueMap being based on Dictionary<IAsyncLocal, object?> and having to compute the hash bucket index and check for hash collisions…? This library might involve more virtual method calls though, so I don't know which one is actually faster.

[KalleOlaviNiemitalo]

It might be best to recategorise this library from stable to experimental until you get someone familiar with it so that it can be supported.