From a8d40ac8362bacd98f7fa422190fe66916e040e8 Mon Sep 17 00:00:00 2001 From: Stephen Toub Date: Wed, 16 May 2018 16:21:02 -0400 Subject: [PATCH] Add some more documentation for ValueTask (dotnet/corefx#29726) * Add some more documentation for ValueTask * Address PR feedback Signed-off-by: dotnet-bot-corefx-mirror --- .../shared/System/Threading/Tasks/ValueTask.cs | 52 ++++++++++++++++++---- 1 file changed, 44 insertions(+), 8 deletions(-) diff --git a/src/System.Private.CoreLib/shared/System/Threading/Tasks/ValueTask.cs b/src/System.Private.CoreLib/shared/System/Threading/Tasks/ValueTask.cs index 8ee1a20..4d6a759 100644 --- a/src/System.Private.CoreLib/shared/System/Threading/Tasks/ValueTask.cs +++ b/src/System.Private.CoreLib/shared/System/Threading/Tasks/ValueTask.cs @@ -32,10 +32,28 @@ namespace System.Threading.Tasks /// Provides an awaitable result of an asynchronous operation. /// - /// s are meant to be directly awaited. To do more complicated operations with them, a - /// should be extracted using . Such operations might include caching an instance to be awaited later, - /// registering multiple continuations with a single operation, awaiting the same task multiple times, and using combinators over - /// multiple operations. + /// instances are meant to be directly awaited. To do more complicated operations with them, a + /// should be extracted using . Such operations might include caching a task instance to be awaited later, + /// registering multiple continuations with a single task, awaiting the same task multiple times, and using combinators over + /// multiple operations: + /// + /// + /// Once the result of a instance has been retrieved, do not attempt to retrieve it again. + /// instances may be backed by instances that are reusable, and such + /// instances may use the act of retrieving the instances result as a notification that the instance may now be reused for + /// a different operation. Attempting to then reuse that same results in undefined behavior. + /// + /// + /// Do not attempt to add multiple continuations to the same . While this might work if the + /// wraps a T or a , it may not work if the + /// was constructed from an . + /// + /// + /// Some operations that return a may invalidate it based on some subsequent operation being performed. + /// Unless otherwise documented, assume that a should be awaited prior to performing any additional operations + /// on the instance from which it was retrieved. + /// + /// /// [AsyncMethodBuilder(typeof(AsyncValueTaskMethodBuilder))] [StructLayout(LayoutKind.Auto)] @@ -408,10 +426,28 @@ namespace System.Threading.Tasks /// Provides a value type that can represent a synchronously available value or a task object. /// Specifies the type of the result. /// - /// s are meant to be directly awaited. To do more complicated operations with them, a - /// should be extracted using or . Such operations might include caching an instance to - /// be awaited later, registering multiple continuations with a single operation, awaiting the same task multiple times, and using - /// combinators over multiple operations. + /// instances are meant to be directly awaited. To do more complicated operations with them, a + /// should be extracted using . Such operations might include caching a task instance to be awaited later, + /// registering multiple continuations with a single task, awaiting the same task multiple times, and using combinators over + /// multiple operations: + /// + /// + /// Once the result of a instance has been retrieved, do not attempt to retrieve it again. + /// instances may be backed by instances that are reusable, and such + /// instances may use the act of retrieving the instances result as a notification that the instance may now be reused for + /// a different operation. Attempting to then reuse that same results in undefined behavior. + /// + /// + /// Do not attempt to add multiple continuations to the same . While this might work if the + /// wraps a T or a , it may not work if the + /// was constructed from an . + /// + /// + /// Some operations that return a may invalidate it based on some subsequent operation being performed. + /// Unless otherwise documented, assume that a should be awaited prior to performing any additional operations + /// on the instance from which it was retrieved. + /// + /// /// [AsyncMethodBuilder(typeof(AsyncValueTaskMethodBuilder<>))] [StructLayout(LayoutKind.Auto)] -- 2.7.4