// 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.Threading;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Threading;
 
namespace Microsoft.CodeAnalysis.Editor.Shared.Utilities;
 
/// <summary>
/// Provides a <see cref="VisualStudio.Threading.JoinableTaskContext"/> which Roslyn code can use for transitioning
/// to the main thread and/or waiting for asynchronous operations when required.
/// </summary>
internal interface IThreadingContext
{
    /// <summary>
    /// Gets a value indicating whether the threading context is configured with a main thread that can be used for
    /// scheduling operations.
    /// </summary>
    /// <remarks>
    /// <para>Existence of a main thread is a requirement for correct runtime behavior (in production) of all types
    /// that depend on <see cref="IThreadingContext"/>, so code is generally not expected to check this property.
    /// However, in some lightweight testing scenarios the main thread will not be used, and the test code avoids
    /// setting up the main thread. This property improves the ability to detect incorrectly configured tests (where
    /// a main thread is expected but not provided) and produce a meaningful error for developers.</para>
    /// </remarks>
    bool HasMainThread
    {
        get;
    }
 
    /// <summary>
    /// Gets the <see cref="VisualStudio.Threading.JoinableTaskContext"/> for use in Roslyn code.
    /// </summary>
    JoinableTaskContext JoinableTaskContext
    {
        get;
    }
 
    /// <summary>
    /// Gets the <see cref="VisualStudio.Threading.JoinableTaskFactory"/> for use in Roslyn code.
    /// </summary>
    JoinableTaskFactory JoinableTaskFactory
    {
        get;
    }
 
    /// <summary>
    /// Gets a <see cref="CancellationToken"/> indicating that disposal has been requested for the threading
    /// context.
    /// </summary>
    CancellationToken DisposalToken
    {
        get;
    }
 
    /// <summary>
    /// Runs an asynchronous operation. If the operation is not complete prior to the time the threading context is
    /// disposed, the operation will block the shutdown.
    /// </summary>
    /// <remarks>
    /// <para>The callback function <paramref name="func"/> is invoked synchronously prior to this method returning.
    /// The entire asynchronous operation performed by <paramref name="func"/> will block shutdown of the threading
    /// context.</para>
    ///
    /// <para>If the threading context is already disposed at the time this is called, the operation is cancelled
    /// without calling <paramref name="func"/>.</para>
    /// </remarks>
    /// <param name="func">The callback function that performs an asynchronous operation.</param>
    JoinableTask RunWithShutdownBlockAsync(Func<CancellationToken, Task> func);
}