Add non generic TaskCompletionSource (#203)

Author: SimonCropp

apiCount.include.md

@@ -1 +1 @@
-**API count: 327**
+**API count: 328**

api_list.include.md

@@ -554,3 +554,4 @@
  * `void NotWhitespace(Span<Char>)`
 
 
+#### TaskCompletionSource

src/Consume/Consume.cs

@@ -476,6 +476,11 @@ void XDocumentSaveAsync()
         document.SaveAsync(new MemoryStream(), SaveOptions.None, CancellationToken.None);
     }
 
+    void NonGenericTaskCompletionSource()
+    {
+        var tcs = new TaskCompletionSource();
+    }
+
 #if FeatureMemory
     void RandomNextBytesSpan()
     {

src/Polyfill/TaskCompletionSource.cs

@@ -0,0 +1,228 @@
+// <auto-generated />
+#pragma warning disable
+
+#if !NET5_0_OR_GREATER
+
+#nullable enable
+
+namespace System.Diagnostics;
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Link = System.ComponentModel.DescriptionAttribute;
+
+/// <summary>
+/// Represents the producer side of a <see cref="Tasks.Task"/> unbound to a
+/// delegate, providing access to the consumer side through the <see cref="Tasks.Task"/> property.
+/// </summary>
+/// <remarks>
+/// <para>
+/// It is often the case that a <see cref="Tasks.Task"/> is desired to
+/// represent another asynchronous operation.
+/// <see cref="TaskCompletionSource">TaskCompletionSource</see> is provided for this purpose. It enables
+/// the creation of a task that can be handed out to consumers, and those consumers can use the members
+/// of the task as they would any other. However, unlike most tasks, the state of a task created by a
+/// TaskCompletionSource is controlled explicitly by the methods on TaskCompletionSource. This enables the
+/// completion of the external asynchronous operation to be propagated to the underlying Task. The
+/// separation also ensures that consumers are not able to transition the state without access to the
+/// corresponding TaskCompletionSource.
+/// </para>
+/// <para>
+/// All members of <see cref="TaskCompletionSource"/> are thread-safe
+/// and may be used from multiple threads concurrently.
+/// </para>
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[DebuggerNonUserCode]
+[Link("https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcompletionsource?view=net-8.0")]
+#if PolyPublic
+public
+#endif
+class TaskCompletionSource
+{
+    TaskCompletionSource<object?> inner;
+
+    /// <summary>Creates a <see cref="TaskCompletionSource"/>.</summary>
+    public TaskCompletionSource() =>
+        inner = new TaskCompletionSource<object>();
+
+    /// <summary>Creates a <see cref="TaskCompletionSource"/> with the specified options.</summary>
+    /// <remarks>
+    /// The <see cref="Tasks.Task"/> created by this instance and accessible through its <see cref="Task"/> property
+    /// will be instantiated using the specified <paramref name="creationOptions"/>.
+    /// </remarks>
+    /// <param name="creationOptions">The options to use when creating the underlying <see cref="Tasks.Task"/>.</param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// The <paramref name="creationOptions"/> represent options invalid for use
+    /// with a <see cref="TaskCompletionSource"/>.
+    /// </exception>
+    public TaskCompletionSource(TaskCreationOptions creationOptions) :
+        this(null, creationOptions)
+    {
+    }
+
+    /// <summary>Creates a <see cref="TaskCompletionSource"/> with the specified state.</summary>
+    /// <param name="state">The state to use as the underlying
+    /// <see cref="Tasks.Task"/>'s AsyncState.</param>
+    public TaskCompletionSource(object? state) :
+        this(state, TaskCreationOptions.None)
+    {
+    }
+
+    /// <summary>Creates a <see cref="TaskCompletionSource"/> with the specified state and options.</summary>
+    /// <param name="creationOptions">The options to use when creating the underlying <see cref="Tasks.Task"/>.</param>
+    /// <param name="state">The state to use as the underlying <see cref="Tasks.Task"/>'s AsyncState.</param>
+    /// <exception cref="ArgumentOutOfRangeException">The <paramref name="creationOptions"/> represent options invalid for use with a <see cref="TaskCompletionSource"/>.</exception>
+    public TaskCompletionSource(object? state, TaskCreationOptions creationOptions) =>
+        inner = new(state, creationOptions);
+
+    /// <summary>
+    /// Gets the <see cref="Tasks.Task"/> created
+    /// by this <see cref="TaskCompletionSource"/>.
+    /// </summary>
+    /// <remarks>
+    /// This property enables a consumer access to the <see cref="Task"/> that is controlled by this instance.
+    /// The <see cref="SetResult"/>, <see cref="SetException(Exception)"/>, <see cref="SetException(IEnumerable{Exception})"/>,
+    /// and <see cref="SetCanceled"/> methods (and their "Try" variants) on this instance all result in the relevant state
+    /// transitions on this underlying Task.
+    /// </remarks>
+    public Task Task => inner.Task;
+
+    /// <summary>Transitions the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Faulted"/> state.</summary>
+    /// <param name="exception">The exception to bind to this <see cref="Tasks.Task"/>.</param>
+    /// <exception cref="ArgumentNullException">The <paramref name="exception"/> argument is null.</exception>
+    /// <exception cref="InvalidOperationException">
+    /// The underlying <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </exception>
+    public void SetException(Exception exception) =>
+        inner.SetException(exception);
+
+    /// <summary>Transitions the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Faulted"/> state.</summary>
+    /// <param name="exceptions">The collection of exceptions to bind to this <see cref="Tasks.Task"/>.</param>
+    /// <exception cref="ArgumentNullException">The <paramref name="exceptions"/> argument is null.</exception>
+    /// <exception cref="ArgumentException">There are one or more null elements in <paramref name="exceptions"/>.</exception>
+    /// <exception cref="InvalidOperationException">
+    /// The underlying <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </exception>
+    public void SetException(IEnumerable<Exception> exceptions) =>
+        inner.SetException(exceptions);
+
+    /// <summary>
+    /// Attempts to transition the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Faulted"/> state.
+    /// </summary>
+    /// <param name="exception">The exception to bind to this <see cref="Tasks.Task"/>.</param>
+    /// <returns>True if the operation was successful; otherwise, false.</returns>
+    /// <remarks>
+    /// This operation will return false if the <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException">The <paramref name="exception"/> argument is null.</exception>
+    public bool TrySetException(Exception exception) =>
+        inner.TrySetException(exception);
+
+    /// <summary>
+    /// Attempts to transition the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Faulted"/> state.
+    /// </summary>
+    /// <param name="exceptions">The collection of exceptions to bind to this <see cref="Tasks.Task"/>.</param>
+    /// <returns>True if the operation was successful; otherwise, false.</returns>
+    /// <remarks>
+    /// This operation will return false if the <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException">The <paramref name="exceptions"/> argument is null.</exception>
+    /// <exception cref="ArgumentException">There are one or more null elements in <paramref name="exceptions"/>.</exception>
+    /// <exception cref="ArgumentException">The <paramref name="exceptions"/> collection is empty.</exception>
+    public bool TrySetException(IEnumerable<Exception> exceptions) =>
+        inner.TrySetException(exceptions);
+
+    /// <summary>
+    /// Transitions the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.RanToCompletion"/> state.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// The underlying <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </exception>
+    public void SetResult() =>
+        inner.SetResult(null);
+
+    /// <summary>
+    /// Attempts to transition the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.RanToCompletion"/> state.
+    /// </summary>
+    /// <returns>True if the operation was successful; otherwise, false.</returns>
+    /// <remarks>
+    /// This operation will return false if the <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </remarks>
+    public bool TrySetResult() =>
+        inner.TrySetResult(null);
+
+    /// <summary>
+    /// Transitions the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Canceled"/> state.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// The underlying <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </exception>
+    public void SetCanceled() => SetCanceled(default);
+
+    /// <summary>
+    /// Transitions the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Canceled"/> state
+    /// using the specified token.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token with which to cancel the <see cref="Tasks.Task"/>.</param>
+    /// <exception cref="InvalidOperationException">
+    /// The underlying <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </exception>
+    public void SetCanceled(CancellationToken cancellationToken) =>
+        inner.SetCanceled(cancellationToken);
+
+    /// <summary>
+    /// Attempts to transition the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Canceled"/> state.
+    /// </summary>
+    /// <returns>True if the operation was successful; otherwise, false.</returns>
+    /// <remarks>
+    /// This operation will return false if the <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </remarks>
+    public bool TrySetCanceled() =>
+        TrySetCanceled(default);
+
+    /// <summary>
+    /// Attempts to transition the underlying <see cref="Tasks.Task"/> into the <see cref="TaskStatus.Canceled"/> state.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token with which to cancel the <see cref="Tasks.Task"/>.</param>
+    /// <returns>True if the operation was successful; otherwise, false.</returns>
+    /// <remarks>
+    /// This operation will return false if the <see cref="Tasks.Task"/> is already in one of the three final states:
+    /// <see cref="TaskStatus.RanToCompletion"/>,
+    /// <see cref="TaskStatus.Faulted"/>, or
+    /// <see cref="TaskStatus.Canceled"/>.
+    /// </remarks>
+    public bool TrySetCanceled(CancellationToken cancellationToken) =>
+        inner.TrySetCanceled(default);
+}
+#endif

src/Tests/BuildApiTest.cs

@@ -65,6 +65,7 @@ public void Run()
         WriteHelper(types, "ULongPolyfill", writer, ref count);
         WriteHelper(types, "UShortPolyfill", writer, ref count);
         WriteHelper(types, "Guard", writer, ref count);
+        WriteType(nameof(TaskCompletionSource), writer, ref count);
 
         count += types.Count(_ => _.Key.EndsWith("Attribute"));
         var countMd = Path.Combine(solutionDirectory, "..", "apiCount.include.md");
@@ -136,6 +137,12 @@ static void WriteHelper(Dictionary<string, List<MethodDefinition>> types, string
         writer.WriteLine();
     }
 
+    static void WriteType(string name, StreamWriter writer, ref int count)
+    {
+        writer.WriteLine($"#### {name}");
+        count++;
+    }
+
     static string GetTypeName(string targetType)
     {
         var name = targetType.Replace("`1", "").Replace("`2", "").Replace("`3", "");

src/Tests/PolyfillTests_TaskCompletionSource.cs

@@ -1,6 +1,23 @@
 #pragma warning disable CS4014
 partial class PolyfillTests
 {
+    [Test]
+    public async Task TaskCompletionSource()
+    {
+        var completionSource = new TaskCompletionSource();
+
+        // Simulate some background work
+        Task.Run(async () =>
+        {
+            await Task.Delay(10); // Simulate a delay
+            completionSource.SetResult();
+        });
+
+        // Await the task
+        await completionSource.Task;
+        Console.WriteLine("Task completed successfully");
+    }
+
     [Test]
     public async Task TaskCompletionSource_SetCanceled_WithCancellationToken()
     {