Merged PR 21067: Clarify IAsyncInfo.Closed and IAsyncXxx.Completed

Clarify IAsyncInfo.Closed and IAsyncXxx.Completed

Closed:
* May not call before operation has completed.
* Implementation permitted to release any associated resources.
* May not call any methods or access any properties.

Completed:
* If you set it after the operation has completed, then the handler is called back "immediately" (subject to whatever the operation's policy is), possibly even recursively from within the setter.

This resolves customer issues
* https://stackoverflow.com/questions/78007860/iasyncoperation-completed-handler-race-conditions
* #2455

Author: oldnewthing

windows.foundation/iasyncaction_completed.md

@@ -10,17 +10,23 @@ public Windows.Foundation.AsyncActionCompletedHandler Completed { get;  set; }
 # Windows.Foundation.IAsyncAction.Completed
 
 ## -description
-Gets or sets the method that handles the action completed notification.
+Gets or sets the delegate that is called when the action completes.
 
 ## -property-value
-The method that handles the notification.
+The delegate that is called when the action completes.
 
 ## -remarks
-The Windows Runtime enforces that this property can only be set once on an action.
+You're not allowed to set the **Completed** property more than once.
 
-Generally, a completed [IAsyncAction](iasyncaction.md) method called using language-specific awaitable syntax does nothing further than to return **null** when it completes.
+Most applications don't use the **Completed** property directly,
+but instead use a language-specific syntax for awaiting the completion
+of an asynchronous action,
+such as `co_await` (C++/WinRT), `await` (C#, Javascript), or `then` (Javascript, C++/CX).
 
-If you're implementing [IAsyncAction](iasyncaction.md), then the set implementation of **Completed** should store the handler, and the surrounding logic should invoke it when [Close](iasyncinfo_close_811482585.md) is called. The implementation should set the *asyncStatus* parameter of invoked callbacks appropriately if there is a [Cancel](iasyncinfo_cancel_1985564044.md) call, [Status](iasyncinfo_status.md) is not **Completed**, errors occurred, and so on.
+If the **Completed** property is set after the action has already completed,
+then the action behaves as if it had completed immediately after the handler was received.
+Note that this can result in the handler being called before the **Completed** property setter
+has returned; possibly even from the same thread.
 
 <!--Needed- topic on roll-your-own async that covers stuff like that-->
 

windows.foundation/iasyncactionwithprogress_1_completed.md

@@ -10,23 +10,28 @@ public Windows.Foundation.AsyncActionWithProgressCompletedHandler<TProgress> Com
 # Windows.Foundation.IAsyncActionWithProgress<TProgress>.Completed
 
 ## -description
-Gets or sets the method that handles the action completed notification.
+Gets or sets the delegate that is called when the action completes.
 
 ## -property-value
-The method that handles the notification.
+The delegate that is called when the action completes.
 
 ## -remarks
-The Windows Runtime enforces that this property can only be set once on an action.
+You're not allowed to set the **Completed** property more than once.
 
-Generally, a completed [IAsyncActionWithProgress<TProgress>](iasyncactionwithprogress_1.md) method called using language-specific awaitable syntax does nothing further than to return **null** when it completes.
-
-If you're implementing [IAsyncActionWithProgress<TProgress>](iasyncactionwithprogress_1.md), then the set implementation of [Completed](iasyncoperationwithprogress_2_completed.md) should store the handler, and the surrounding logic should invoke it when [Close](iasyncinfo_close_811482585.md) is called. The implementation should set the *asyncStatus* parameter of invoked callbacks appropriately if there is a [Cancel](iasyncinfo_cancel_1985564044.md) call, [Status](iasyncinfo_status.md) is not **Completed**, errors occurred, and so on.
+Most applications don't use the **Completed** property directly,
+but instead use a language-specific syntax for awaiting the completion
+of an asynchronous action,
+such as `co_await` (C++/WinRT), `await` (C#, Javascript), or `then` (Javascript, C++/CX).
 
+If the **Completed** property is set after the action has already completed,
+then the action behaves as if it had completed immediately after the handler was received.
+Note that this can result in the handler being called before the **Completed** property setter
+has returned; possibly even from the same thread.
 
 <!--Needed- topic on roll-your-own async that covers stuff like that-->
 
 ## -examples
 For example [C++/WinRT](/windows/uwp/cpp-and-winrt-apis/) code illustrating how to handle the **Completed** event, see [Delegate types for asynchronous actions and operations](/windows/uwp/cpp-and-winrt-apis/handle-events#delegate-types-for-asynchronous-actions-and-operations).
 
 ## -see-also
-[IAsyncActionWithProgress&lt;TProgress&gt;](iasyncactionwithprogress_1.md)
+[IAsyncActionWithProgress&lt;TProgress&gt;](iasyncactionwithprogress_1.md)

windows.foundation/iasyncinfo_close_811482585.md

@@ -13,9 +13,12 @@ public void Close()
 Closes the asynchronous operation.
 
 ## -remarks
-Calling this method indicates that you have finished with the results of the operation. After calling Close, do not call the **GetResults** method again (each of the 4 [IAsyncInfo](iasyncinfo.md) derived interfaces have their own implementation of **GetResults**.)
+Calling this method indicates that you have finished with the asynchronous action or operation,
+and it is permitted to free any associated resources.
+After calling **Close**, you may not call any methods or access any properties
+of the object that implements the [IAsyncInfo](iasyncinfo.md) interface.
 
-<!--Is this a Notes to Callers? It's a weird note for implementation purposes.-->
+You may not call **Close** before the asynchronous action or operation has completed.
 
 ## -examples
 

windows.foundation/iasyncoperation_1_completed.md

@@ -10,18 +10,23 @@ public Windows.Foundation.AsyncOperationCompletedHandler<TResult> Completed { ge
 # Windows.Foundation.IAsyncOperation<TResult>.Completed
 
 ## -description
-Gets or sets the method that handles the operation completed notification.
+Gets or sets the delegate that is called when the operation completes.
 
 ## -property-value
-The method that handles the notification.
+The delegate that is called when the operation completes.
 
 ## -remarks
-The Windows Runtime enforces that this property can only be set once on an operation.
+You're not allowed to set the **Completed** property more than once.
 
-Generally, a completed [IAsyncOperation<TResult>](iasyncoperation_1.md) method called using awaitable syntax does nothing further than to return its result (an object of the **TResult** type) when it completes.
-
-If you're implementing [IAsyncOperation<TResult>](iasyncoperation_1.md), then the set implementation of [Completed](iasyncaction_completed.md) should store the handler, and the surrounding logic should invoke it when [Close](iasyncinfo_close_811482585.md) is called. The implementation should set the *asyncStatus* parameter of invoked callbacks appropriately if there is a [Cancel](iasyncinfo_cancel_1985564044.md) call, [Status](iasyncinfo_status.md) is not **Completed**, errors occurred, and so on.
+Most applications don't use the **Completed** property directly,
+but instead use a language-specific syntax for awaiting the completion
+of an asynchronous action,
+such as `co_await` (C++/WinRT), `await` (C#, Javascript), or `then` (Javascript, C++/CX).
 
+If the **Completed** property is set after the action has already completed,
+then the action behaves as if it had completed immediately after the handler was received.
+Note that this can result in the handler being called before the **Completed** property setter
+has returned; possibly even from the same thread.
 
 <!--Needed- topic on roll-your-own async that covers stuff like that-->
 

windows.foundation/iasyncoperationwithprogress_2_completed.md

@@ -10,17 +10,23 @@ public Windows.Foundation.AsyncOperationWithProgressCompletedHandler<TResult, TP
 # Windows.Foundation.IAsyncOperationWithProgress<TResult, TProgress>.Completed
 
 ## -description
-Gets or sets the method that handles the operation completed notification.
+Gets or sets the delegate that is called when the operation completes.
 
 ## -property-value
-The method that handles the notification.
+The delegate that is called when the operation completes.
 
 ## -remarks
-The Windows Runtime enforces that this property can only be set once on an operation.
+You're not allowed to set the **Completed** property more than once.
 
-Generally, a completed [AsyncOperationWithProgressCompletedHandler<TResult, TProgress>](asyncoperationwithprogresscompletedhandler_2.md) method called using awaitable syntax does nothing further than to return its result (an object of the **TResult** type) when it completes.
+Most applications don't use the **Completed** property directly,
+but instead use a language-specific syntax for awaiting the completion
+of an asynchronous action,
+such as `co_await` (C++/WinRT), `await` (C#, Javascript), or `then` (Javascript, C++/CX).
 
-If you're implementing [AsyncOperationWithProgressCompletedHandler<TResult, TProgress>](asyncoperationwithprogresscompletedhandler_2.md), then the set implementation of [Completed](iasyncaction_completed.md) should store the handler, and the surrounding logic should invoke it when [Close](iasyncinfo_close_811482585.md) is called. The implementation should set the *asyncStatus* parameter of invoked callbacks appropriately if there is a [Cancel](iasyncinfo_cancel_1985564044.md) call, [Status](iasyncinfo_status.md) is not **Completed**, errors occurred, and so on.
+If the **Completed** property is set after the action has already completed,
+then the action behaves as if it had completed immediately after the handler was received.
+Note that this can result in the handler being called before the **Completed** property setter
+has returned; possibly even from the same thread.
 
 ## -examples
 For example [C++/WinRT](/windows/uwp/cpp-and-winrt-apis/) code illustrating how to handle the **Completed** event, see [Delegate types for asynchronous actions and operations](/windows/uwp/cpp-and-winrt-apis/handle-events#delegate-types-for-asynchronous-actions-and-operations).