Add sos DumpAsync command (#18160)

Debugging async methods with sos can be time consuming and relies on knowing how to use dumpheap, dumpvc, gcroot, and other commands to get the desired information, while often digging through a myriad of objects on the heap to find the desired info.

This commit adds a new DumpAsync command, which finds the async state machine objects on the GC heap and outputs relevant information about each, including the fields of its state machine, any registered continuation, and GC roots for the state machine object (as they often serve as a valid substitute for call stacks).

Example program used as a test:
```C#
using System.Threading.Tasks;

class Program
{
    static async Task Main() => await MethodA();
    static async Task MethodA() => await MethodB();
    static async Task MethodB() => await MethodC();
    static async Task MethodC() => await MethodD();
    static async Task MethodD() => await Task.Delay(int.MaxValue);
}
```
and example command output:
```
0:011> !DumpAsync -type MethodD
         Address               MT     Size Name
000001989f413de0 00007ff88c506ba8      112  System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
StateMachine: Program+<MethodD>d__4
              MT    Field   Offset                 Type VT     Attr            Value Name
00007ff8d3df4b80  400000d        0         System.Int32  1 instance                0 <>1__state
00007ff8d3e082c0  400000e        8 ...TaskMethodBuilder  1 instance 000001989f413e38 <>t__builder
00007ff8d3dfea90  400000f       10 ...vices.TaskAwaiter  1 instance 000001989f413e40 <>u__1
Continuation: 000001989f413e50 (System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]])
GC roots:
    Thread 2936c:
        000000071a37e050 00007ff8d3ac1657 System.Threading.Tasks.Task.SpinThenBlockingWait(Int32, System.Threading.CancellationToken) [d:\repos\coreclr\src\System.Private.CoreLib\src\System\Threading\Tasks\Task.cs @ 2977]
            rbp+10: 000000071a37e0c0
                ->  000001989f413fa0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<Main>d__0, test]]
                ->  000001989f413f30 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodA>d__1, test]]
                ->  000001989f413ec0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodB>d__2, test]]
                ->  000001989f413e50 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]]
                ->  000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]

    HandleTable:
        000001989d8415f8 (pinned handle)
        -> 00000198af3e1038 System.Object[]
        -> 000001989f413410 System.Threading.TimerQueue[]
        -> 000001989f413468 System.Threading.TimerQueue
        -> 000001989f413330 System.Threading.TimerQueueTimer
        -> 000001989f412e40 System.Threading.Tasks.Task+DelayPromise
        -> 000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]

Found 1 state machines.
```

src/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncMethodBuilder.cs

@@ -498,7 +498,7 @@ private IAsyncStateMachineBox GetStateMachineBox<TStateMachine>(
         /// event about the state machine if it's being finalized without having been completed.
         /// </summary>
         /// <typeparam name="TStateMachine">Specifies the type of the state machine.</typeparam>
-        private sealed class DebugFinalizableAsyncStateMachineBox<TStateMachine> :
+        private sealed class DebugFinalizableAsyncStateMachineBox<TStateMachine> : // SOS DumpAsync command depends on this name
             AsyncStateMachineBox<TStateMachine>
             where TStateMachine : IAsyncStateMachine
         {
@@ -517,7 +517,7 @@ private sealed class DebugFinalizableAsyncStateMachineBox<TStateMachine> :
         /// <summary>A strongly-typed box for Task-based async state machines.</summary>
         /// <typeparam name="TStateMachine">Specifies the type of the state machine.</typeparam>
         /// <typeparam name="TResult">Specifies the type of the Task's result.</typeparam>
-        private class AsyncStateMachineBox<TStateMachine> :
+        private class AsyncStateMachineBox<TStateMachine> : // SOS DumpAsync command depends on this name
             Task<TResult>, IAsyncStateMachineBox
             where TStateMachine : IAsyncStateMachine
         {
@@ -527,7 +527,7 @@ private class AsyncStateMachineBox<TStateMachine> :
             /// <summary>A delegate to the <see cref="MoveNext"/> method.</summary>
             private Action _moveNextAction;
             /// <summary>The state machine itself.</summary>
-            public TStateMachine StateMachine; // mutable struct; do not make this readonly
+            public TStateMachine StateMachine; // mutable struct; do not make this readonly. SOS DumpAsync command depends on this name.
             /// <summary>Captured ExecutionContext with which to invoke <see cref="MoveNextAction"/>; may be null.</summary>
             public ExecutionContext Context;
 

src/System.Private.CoreLib/src/System/Threading/Tasks/Task.cs

@@ -193,7 +193,7 @@ public class Task : IThreadPoolWorkItem, IAsyncResult, IDisposable
 
         // Can be null, a single continuation, a list of continuations, or s_taskCompletionSentinel,
         // in that order. The logic arround this object assumes it will never regress to a previous state.
-        private volatile object m_continuationObject = null;
+        private volatile object m_continuationObject = null; // SOS DumpAsync command depends on this name
 
         // m_continuationObject is set to this when the task completes.
         private static readonly object s_taskCompletionSentinel = new object();

src/ToolBox/SOS/Strike/apollososdocs.txt

@@ -25,16 +25,16 @@ Object Inspection                  Examining code and stacks
 -----------------------------      -----------------------------
 DumpObj (do)                       Threads
 DumpArray (da)                     ThreadState
-DumpStackObjects (dso)             IP2MD
-DumpHeap                           U
-DumpVC                             DumpStack
-GCRoot                             EEStack
-ObjSize                            CLRStack
-FinalizeQueue                      GCInfo
-PrintException (pe)                EHInfo
-TraverseHeap                       BPMD 
-Watch                              COMState
-                                   StopOnCatch
+DumpAsync                          IP2MD
+DumpStackObjects (dso)             U
+DumpHeap                           DumpStack
+DumpVC                             EEStack
+GCRoot                             CLRStack
+ObjSize                            GCInfo
+FinalizeQueue                      EHInfo
+PrintException (pe)                BPMD
+TraverseHeap                       COMState 
+Watch                              StopOnCatch
                                    SuppressJitOptimization
 
 Examining CLR data structures      Diagnostic Utilities
@@ -340,6 +340,62 @@ The arguments in detail:
 	    5b9a628c  4000002        4         System.Int32   instance        8 y
 	    5b9a628c  4000003        8         System.Int32   instance       12 z
 
+\\
+
+COMMAND: dumpasync.
+!DumpAsync [-mt <MethodTable address>] 
+           [-type <partial type name>]]
+
+!DumpAsync traverses the garbage collected heap, looking for objects representing
+async state machines as created when an async method's state is transferred to the
+heap.  This command recognizes async state machines defined as "async void", "async Task",
+"async Task<T>", "async ValueTask", and "async ValueTask<T>".
+
+The output includes a block of details for each async state machine object found.
+These details include:
+    - a line for the type of the async state machine object, including its MethodTable address,
+      its object address, its size, and its type name.
+    - a line for the state machine type name as contained in the object.
+    - a listing of each field on the state machine.
+    - a line for a continuation from this state machine object, if one or more has been registered.
+    - discovered GC roots for this async state machine object.
+
+For example:
+
+    0:011> !DumpAsync
+    #0
+    000001989f413de0 00007ff88c506ba8      112  System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    StateMachine: Program+<MethodD>d__4 (struct)
+                  MT    Field   Offset                 Type VT     Attr            Value Name
+    00007ff8d3df4b80  400000d        0         System.Int32  1 instance                0 <>1__state
+    00007ff8d3e082c0  400000e        8 ...TaskMethodBuilder  1 instance 000001989f413e38 <>t__builder
+    00007ff8d3dfea90  400000f       10 ...vices.TaskAwaiter  1 instance 000001989f413e40 <>u__1
+    Continuation: 000001989f413e50 (System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]])
+    GC roots:
+        Thread 2936c:
+            000000071a37e050 00007ff8d3ac1657 System.Threading.Tasks.Task.SpinThenBlockingWait(Int32, System.Threading.CancellationToken) [d:\repos\coreclr\src\System.Private.CoreLib\src\System\Threading\Tasks\Task.cs @ 2977]
+                rbp+10: 000000071a37e0c0
+                    ->  000001989f413fa0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<Main>d__0, test]]
+                    ->  000001989f413f30 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodA>d__1, test]]
+                    ->  000001989f413ec0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodB>d__2, test]]
+                    ->  000001989f413e50 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]]
+                    ->  000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+        HandleTable:
+            000001989d8415f8 (pinned handle)
+            -> 00000198af3e1038 System.Object[]
+            -> 000001989f413410 System.Threading.TimerQueue[]
+            -> 000001989f413468 System.Threading.TimerQueue
+            -> 000001989f413330 System.Threading.TimerQueueTimer
+            -> 000001989f412e40 System.Threading.Tasks.Task+DelayPromise
+            -> 000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    ...
+
+
+The arguments in detail:
+
+-mt       List only those state machine objects with the MethodTable given.
+-type     List only those state machine objects whose type name is a
+          substring match of the string provided.
 
 \\
 

src/ToolBox/SOS/Strike/sos.def

@@ -15,6 +15,8 @@ EXPORTS
     dumparray=DumpArray
     DumpAssembly
     dumpassembly=DumpAssembly
+    DumpAsync
+    dumpasync=DumpAsync
     DumpClass
     dumpclass=DumpClass
     DumpDomain

src/ToolBox/SOS/Strike/sos_unixexports.src

@@ -7,6 +7,7 @@ ClrStack
 CreateDump
 DumpArray
 DumpAssembly
+DumpAsync
 DumpClass
 DumpDomain
 DumpGCData

src/ToolBox/SOS/Strike/sosdocs.txt

@@ -25,15 +25,15 @@ Object Inspection                  Examining code and stacks
 -----------------------------      -----------------------------
 DumpObj (do)                       Threads
 DumpArray (da)                     ThreadState
-DumpStackObjects (dso)             IP2MD
-DumpHeap                           U
-DumpVC                             DumpStack
-GCRoot                             EEStack
-ObjSize                            CLRStack
-FinalizeQueue                      GCInfo
-PrintException (pe)                EHInfo
-TraverseHeap                       BPMD 
-                                   COMState
+DumpAsync                          IP2MD
+DumpStackObjects (dso)             U
+DumpHeap                           DumpStack
+DumpVC                             EEStack
+GCRoot                             CLRStack
+ObjSize                            GCInfo
+FinalizeQueue                      EHInfo
+PrintException (pe)                BPMD
+TraverseHeap                       COMState
 
 Examining CLR data structures      Diagnostic Utilities
 -----------------------------      -----------------------------
@@ -338,6 +338,62 @@ The arguments in detail:
 	    5b9a628c  4000002        4         System.Int32   instance        8 y
 	    5b9a628c  4000003        8         System.Int32   instance       12 z
 
+\\
+
+COMMAND: dumpasync.
+!DumpAsync [-mt <MethodTable address>] 
+           [-type <partial type name>]]
+
+!DumpAsync traverses the garbage collected heap, looking for objects representing
+async state machines as created when an async method's state is transferred to the
+heap.  This command recognizes async state machines defined as "async void", "async Task",
+"async Task<T>", "async ValueTask", and "async ValueTask<T>".
+
+The output includes a block of details for each async state machine object found.
+These details include:
+    - a line for the type of the async state machine object, including its MethodTable address,
+      its object address, its size, and its type name.
+    - a line for the state machine type name as contained in the object.
+    - a listing of each field on the state machine.
+    - a line for a continuation from this state machine object, if one or more has been registered.
+    - discovered GC roots for this async state machine object.
+
+For example:
+
+    0:011> !DumpAsync
+    #0
+    000001989f413de0 00007ff88c506ba8      112  System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    StateMachine: Program+<MethodD>d__4 (struct)
+                  MT    Field   Offset                 Type VT     Attr            Value Name
+    00007ff8d3df4b80  400000d        0         System.Int32  1 instance                0 <>1__state
+    00007ff8d3e082c0  400000e        8 ...TaskMethodBuilder  1 instance 000001989f413e38 <>t__builder
+    00007ff8d3dfea90  400000f       10 ...vices.TaskAwaiter  1 instance 000001989f413e40 <>u__1
+    Continuation: 000001989f413e50 (System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]])
+    GC roots:
+        Thread 2936c:
+            000000071a37e050 00007ff8d3ac1657 System.Threading.Tasks.Task.SpinThenBlockingWait(Int32, System.Threading.CancellationToken) [d:\repos\coreclr\src\System.Private.CoreLib\src\System\Threading\Tasks\Task.cs @ 2977]
+                rbp+10: 000000071a37e0c0
+                    ->  000001989f413fa0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<Main>d__0, test]]
+                    ->  000001989f413f30 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodA>d__1, test]]
+                    ->  000001989f413ec0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodB>d__2, test]]
+                    ->  000001989f413e50 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]]
+                    ->  000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+        HandleTable:
+            000001989d8415f8 (pinned handle)
+            -> 00000198af3e1038 System.Object[]
+            -> 000001989f413410 System.Threading.TimerQueue[]
+            -> 000001989f413468 System.Threading.TimerQueue
+            -> 000001989f413330 System.Threading.TimerQueueTimer
+            -> 000001989f412e40 System.Threading.Tasks.Task+DelayPromise
+            -> 000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    ...
+
+
+The arguments in detail:
+
+-mt       List only those state machine objects with the MethodTable given.
+-type     List only those state machine objects whose type name is a
+          substring match of the string provided.
 
 \\
 

src/ToolBox/SOS/Strike/sosdocsunix.txt

@@ -25,12 +25,12 @@ Object Inspection                  Examining code and stacks
 -----------------------------      -----------------------------
 DumpObj (dumpobj)                  Threads (clrthreads)
 DumpArray                          ThreadState
-DumpStackObjects (dso)             IP2MD (ip2md)
-DumpHeap (dumpheap)                u (clru)
-DumpVC                             DumpStack (dumpstack)
-GCRoot (gcroot)                    EEStack (eestack)
-PrintException (pe)                ClrStack (clrstack) 
-                                   GCInfo
+DumpAsync (dumpasync)              IP2MD (ip2md)
+DumpStackObjects (dso)             u (clru)
+DumpHeap (dumpheap)                DumpStack (dumpstack)
+DumpVC                             EEStack (eestack)
+GCRoot (gcroot)                    CLRStack (clrstack)
+PrintException (pe)                GCInfo
                                    EHInfo
                                    bpmd (bpmd)
 
@@ -199,6 +199,62 @@ The arguments in detail:
 	    5b9a628c  4000002        4         System.Int32   instance        8 y
 	    5b9a628c  4000003        8         System.Int32   instance       12 z
 
+\\
+
+COMMAND: dumpasync.
+!DumpAsync [-mt <MethodTable address>] 
+           [-type <partial type name>]]
+
+!DumpAsync traverses the garbage collected heap, looking for objects representing
+async state machines as created when an async method's state is transferred to the
+heap.  This command recognizes async state machines defined as "async void", "async Task",
+"async Task<T>", "async ValueTask", and "async ValueTask<T>".
+
+The output includes a block of details for each async state machine object found.
+These details include:
+    - a line for the type of the async state machine object, including its MethodTable address,
+      its object address, its size, and its type name.
+    - a line for the state machine type name as contained in the object.
+    - a listing of each field on the state machine.
+    - a line for a continuation from this state machine object, if one or more has been registered.
+    - discovered GC roots for this async state machine object.
+
+For example:
+
+    (lldb) dumpasync
+    #0
+    000001989f413de0 00007ff88c506ba8      112  System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    StateMachine: Program+<MethodD>d__4 (struct)
+                  MT    Field   Offset                 Type VT     Attr            Value Name
+    00007ff8d3df4b80  400000d        0         System.Int32  1 instance                0 <>1__state
+    00007ff8d3e082c0  400000e        8 ...TaskMethodBuilder  1 instance 000001989f413e38 <>t__builder
+    00007ff8d3dfea90  400000f       10 ...vices.TaskAwaiter  1 instance 000001989f413e40 <>u__1
+    Continuation: 000001989f413e50 (System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]])
+    GC roots:
+        Thread 2936c:
+            000000071a37e050 00007ff8d3ac1657 System.Threading.Tasks.Task.SpinThenBlockingWait(Int32, System.Threading.CancellationToken) [d:\repos\coreclr\src\System.Private.CoreLib\src\System\Threading\Tasks\Task.cs @ 2977]
+                rbp+10: 000000071a37e0c0
+                    ->  000001989f413fa0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<Main>d__0, test]]
+                    ->  000001989f413f30 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodA>d__1, test]]
+                    ->  000001989f413ec0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodB>d__2, test]]
+                    ->  000001989f413e50 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodC>d__3, test]]
+                    ->  000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+        HandleTable:
+            000001989d8415f8 (pinned handle)
+            -> 00000198af3e1038 System.Object[]
+            -> 000001989f413410 System.Threading.TimerQueue[]
+            -> 000001989f413468 System.Threading.TimerQueue
+            -> 000001989f413330 System.Threading.TimerQueueTimer
+            -> 000001989f412e40 System.Threading.Tasks.Task+DelayPromise
+            -> 000001989f413de0 System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Program+<MethodD>d__4, test]]
+    ...
+
+
+The arguments in detail:
+
+-mt       List only those state machine objects with the MethodTable given.
+-type     List only those state machine objects whose type name is a
+          substring match of the string provided.
 
 \\