// 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.
 
using System;
using System.Diagnostics.CodeAnalysis;
using System.Threading;
using System.Threading.Tasks;
 
namespace Microsoft.CodeAnalysis.Shared.TestHooks
{
    internal interface IExpeditableDelaySource
    {
        /// <summary>
        /// Creates a task that will complete after a time delay, but can be expedited if an operation is waiting for
        /// the task to complete.
        /// </summary>
        /// <param name="delay">The time to wait before completing the returned task, or <c>TimeSpan.FromMilliseconds(-1)</c> to wait indefinitely.</param>
        /// <param name="cancellationToken">A cancellation token to observe while waiting for the task to complete.</param>
        /// <returns><see langword="true"/> if the delay compeleted normally; otherwise, <see langword="false"/> if the delay completed due to a request to expedite the delay.</returns>
        /// <exception cref="ArgumentOutOfRangeException">
        /// <para><paramref name="delay"/> represents a negative time interval other than <c>TimeSpan.FromMilliseconds(-1)</c>.</para>
        /// <para>-or-</para>
        /// <para>The <paramref name="delay"/> argument's <see cref="TimeSpan.TotalMilliseconds"/> property is greater than <see cref="int.MaxValue"/>.</para>
        /// </exception>
        /// <exception cref="OperationCanceledException">The delay has been canceled.</exception>
        [SuppressMessage("Style", """VSTHRD200:Use "Async" suffix for async methods""", Justification = "Named after 'Task.Delay'")]
        Task<bool> Delay(TimeSpan delay, CancellationToken cancellationToken);
    }
}