Added timeout support

Author: sakno

src/DotNext.Tests/Threading/CancellationTokenMultiplexerTests.cs

@@ -71,4 +71,17 @@ public static void ExtraListOverflow()
         using var scope = multiplexer.Combine(tokens);
         True(scope.Token.IsCancellationRequested);
     }
+
+    [Fact]
+    public static async Task TimeOut()
+    {
+        using var cts = new CancellationTokenSource();
+        var multiplexer = new CancellationTokenMultiplexer();
+
+        await using var scope = multiplexer.Combine(TimeSpan.FromMilliseconds(1), [cts.Token]);
+        await scope.Token.WaitAsync();
+
+        Equal(scope.Token, scope.CancellationOrigin);
+        NotEqual(scope.Token, cts.Token);
+    }
 }

src/DotNext.Threading/Threading/CancellationTokenMultiplexer.Scope.cs

@@ -26,6 +26,13 @@ internal Scope(CancellationTokenMultiplexer multiplexer, ReadOnlySpan<Cancellati
             source = multiplexer.Rent(tokens);
         }
 
+        internal Scope(CancellationTokenMultiplexer multiplexer, TimeSpan timeout, ReadOnlySpan<CancellationToken> tokens)
+        {
+            multiplexerOrToken = new(multiplexer);
+            source = multiplexer.Rent(tokens);
+            source.CancelAfter(timeout);
+        }
+
         internal Scope(CancellationToken token)
             => multiplexerOrToken = InlineToken(token);
 
@@ -86,13 +93,13 @@ private static async ValueTask ReturnAsync(CancellationTokenMultiplexer multiple
         private static void Return(CancellationTokenMultiplexer multiplexer, PooledCancellationTokenSource source)
         {
             source.Reset();
-            if (source.IsCancellationRequested)
+            if (source.TryReset())
             {
-                source.Dispose();
+                multiplexer.Return(source);
             }
             else
             {
-                multiplexer.Return(source);
+                source.Dispose();
             }
         }
     }

src/DotNext.Threading/Threading/CancellationTokenMultiplexer.cs

@@ -63,6 +63,24 @@ public Scope Combine(ReadOnlySpan<CancellationToken> tokens) // TODO: use params
         return scope;
     }
 
+    /// <summary>
+    /// Combines the multiple tokens and the timeout.
+    /// </summary>
+    /// <remarks>
+    /// The cancellation triggered by the timeout can be detected by comparing <see cref="Scope.Token"/> with <see cref="Scope.CancellationOrigin"/>.
+    /// </remarks>
+    /// <param name="timeout">The timeout that could trigger the cancellation.</param>
+    /// <param name="tokens">The tokens to be combined.</param>
+    /// <returns>The scope that represents the multiplexed token.</returns>
+    /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is negative or too large.</exception>
+    public Scope Combine(TimeSpan timeout, ReadOnlySpan<CancellationToken> tokens) => timeout.Ticks switch
+    {
+        0L => new(new CancellationToken(canceled: true)),
+        Timeout.InfiniteTicks => Combine(tokens),
+        < 0L or > Timeout.MaxTimeoutParameterTicks => throw new ArgumentOutOfRangeException(nameof(timeout)),
+        _ => new(this, timeout, tokens)
+    };
+
     private void Return(PooledCancellationTokenSource source)
     {
         // try to increment the counter