// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
 
// NOTE: This code is derived from an implementation originally in dotnet/project-system:
// https://github.com/dotnet/project-system/blob/bdf69d5420ec8d894f5bf4c3d4692900b7f2479c/src/Microsoft.VisualStudio.ProjectSystem.Managed/Threading/Tasks/CancellationSeries.cs
//
// See the commentary in https://github.com/dotnet/roslyn/pull/50156 for notes on incorporating changes made to the
// reference implementation.
 
using System;
using System.Threading;
 
namespace Roslyn.Utilities
{
    /// <summary>
    /// Produces a series of <see cref="CancellationToken"/> objects such that requesting a new token
    /// causes the previously issued token to be cancelled.
    /// </summary>
    /// <remarks>
    /// <para>Consuming code is responsible for managing overlapping asynchronous operations.</para>
    /// <para>This class has a lock-free implementation to minimise latency and contention.</para>
    /// </remarks>
    internal sealed class CancellationSeries : IDisposable
    {
        private CancellationTokenSource? _cts;
 
        private readonly CancellationToken _superToken;
 
        /// <summary>
        /// Initializes a new instance of <see cref="CancellationSeries"/>.
        /// </summary>
        /// <param name="token">An optional cancellation token that, when cancelled, cancels the last
        /// issued token and causes any subsequent tokens to be issued in a cancelled state.</param>
        public CancellationSeries(CancellationToken token = default)
        {
            // Initialize with a pre-cancelled source to ensure HasActiveToken has the correct state
            _cts = new CancellationTokenSource();
            _cts.Cancel();
 
            _superToken = token;
        }
 
        /// <summary>
        /// Determines if the cancellation series has an active token which has not been cancelled.
        /// </summary>
        public bool HasActiveToken
            => _cts is { IsCancellationRequested: false };
 
        /// <summary>
        /// Creates the next <see cref="CancellationToken"/> in the series, ensuring the last issued
        /// token (if any) is cancelled first.
        /// </summary>
        /// <param name="token">An optional cancellation token that, when cancelled, cancels the
        /// returned token.</param>
        /// <returns>
        /// A cancellation token that will be cancelled when either:
        /// <list type="bullet">
        /// <item><see cref="CreateNext"/> is called again</item>
        /// <item>The token passed to this method (if any) is cancelled</item>
        /// <item>The token passed to the constructor (if any) is cancelled</item>
        /// <item><see cref="Dispose"/> is called</item>
        /// </list>
        /// </returns>
        /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
        public CancellationToken CreateNext(CancellationToken token = default)
        {
            var nextSource = CancellationTokenSource.CreateLinkedTokenSource(token, _superToken);
 
            // Obtain the token before exchange, as otherwise the CTS may be cancelled before
            // we request the Token, which will result in an ObjectDisposedException.
            // This way we would return a cancelled token, which is reasonable.
            var nextToken = nextSource.Token;
 
            // The following block is identical to Interlocked.Exchange, except no replacement is made if the current
            // field value is null (latch on null). This ensures state is not corrupted if CreateNext is called after
            // the object is disposed.
            var priorSource = Volatile.Read(ref _cts);
            while (priorSource is not null)
            {
                var candidate = Interlocked.CompareExchange(ref _cts, nextSource, priorSource);
 
                if (candidate == priorSource)
                {
                    break;
                }
                else
                {
                    priorSource = candidate;
                }
            }
 
            if (priorSource == null)
            {
                nextSource.Dispose();
 
                throw new ObjectDisposedException(nameof(CancellationSeries));
            }
 
            try
            {
                priorSource.Cancel();
            }
            finally
            {
                // A registered action on the token may throw, which would surface here.
                // Ensure we always dispose the prior CTS.
                priorSource.Dispose();
            }
 
            return nextToken;
        }
 
        public void Dispose()
        {
            var source = Interlocked.Exchange(ref _cts, null);
 
            if (source == null)
            {
                // Already disposed
                return;
            }
 
            try
            {
                source.Cancel();
            }
            finally
            {
                source.Dispose();
            }
        }
    }
}