|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System;
using BuildResult = Microsoft.Build.Execution.BuildResult;
using NodeLoggingContext = Microsoft.Build.BackEnd.Logging.NodeLoggingContext;
#nullable disable
namespace Microsoft.Build.BackEnd
{
#region Delegates
/// <summary>
/// Callback for event raised when a build request is completed
/// </summary>
/// <param name="request">The request which completed</param>
/// <param name="result">The result for the request</param>
internal delegate void RequestCompleteDelegate(BuildRequest request, BuildResult result);
/// <summary>
/// Callback for event raised when a request is resumed
/// </summary>
/// <param name="request">The request being resumed</param>
internal delegate void RequestResumedDelegate(BuildRequest request);
/// <summary>
/// Callback for event raised when a new build request is generated by an MSBuild callback
/// </summary>
/// <param name="blocker">Information about what is blocking the engine.</param>
internal delegate void RequestBlockedDelegate(BuildRequestBlocker blocker);
/// <summary>
/// Callback for event raised when the build request engine's status changes.
/// </summary>
/// <param name="newStatus">The new status for the engine</param>
internal delegate void EngineStatusChangedDelegate(BuildRequestEngineStatus newStatus);
/// <summary>
/// Callback for event raised when a new configuration needs an ID resolved.
/// </summary>
/// <param name="config">The configuration needing an ID</param>
internal delegate void NewConfigurationRequestDelegate(BuildRequestConfiguration config);
/// <summary>
/// Callback for event raised when a resource is requested.
/// </summary>
/// <param name="request">The resources being requested</param>
internal delegate void ResourceRequestDelegate(ResourceRequest request);
/// <summary>
/// Callback for event raised when there is an unhandled exception in the engine.
/// </summary>
/// <param name="e">The exception.</param>
internal delegate void EngineExceptionDelegate(Exception e);
#endregion
/// <summary>
/// Status types for the build request engine
/// </summary>
internal enum BuildRequestEngineStatus
{
/// <summary>
/// The engine has not yet been initialized, and cannot accept requests.
/// </summary>
Uninitialized,
/// <summary>
/// The engine has no active or waiting build requests.
/// </summary>
Idle,
/// <summary>
/// The engine is presently working on a build request.
/// </summary>
Active,
/// <summary>
/// The engine has only build requests which are waiting for build results to continue.
/// </summary>
Waiting,
/// <summary>
/// The engine has shut down.
/// </summary>
Shutdown
}
/// <summary>
/// Objects implementing this interface may be used by a Node to process build requests
/// and generate build results.
/// </summary>
internal interface IBuildRequestEngine
{
#region Events
/// <summary>
/// Raised when a build request is completed and results are available.
/// </summary>
event RequestCompleteDelegate OnRequestComplete;
/// <summary>
/// Raised when a build request is resumed from a previously waiting state.
/// </summary>
event RequestResumedDelegate OnRequestResumed;
/// <summary>
/// Raised when a new build request is generated by an MSBuild callback.
/// </summary>
event RequestBlockedDelegate OnRequestBlocked;
/// <summary>
/// Raised when the engine status changes.
/// </summary>
event EngineStatusChangedDelegate OnStatusChanged;
/// <summary>
/// Raised when a configuration needs an id.
/// </summary>
event NewConfigurationRequestDelegate OnNewConfigurationRequest;
/// <summary>
/// Raised when resources are requested.
/// </summary>
event ResourceRequestDelegate OnResourceRequest;
/// <summary>
/// Raised when an unhandled exception occurs in the engine.
/// </summary>
event EngineExceptionDelegate OnEngineException;
#endregion
#region Properties
/// <summary>
/// Gets the current engine status.
/// </summary>
BuildRequestEngineStatus Status { get; }
#endregion
#region Methods
/// <summary>
/// Prepares the engine for a new build and spins up the engine thread.
/// The engine must be in the Idle state, and not already be initialized.
/// </summary>
/// <param name="loggingContext">The logging context for the node.</param>
void InitializeForBuild(NodeLoggingContext loggingContext);
/// <summary>
/// Cleans up after a build but leaves the engine thread running. Aborts
/// any outstanding requests. Blocks until the engine has cleaned up
/// everything. After this method is called, InitializeForBuild may be
/// called to start a new build, or the component may be shut down.
/// </summary>
void CleanupForBuild();
/// <summary>
/// Submits the specified request to the build queue.
/// </summary>
/// <param name="request">The request to build.</param>
/// <remarks>It is only valid to call this method when the engine is in the Idle or
/// Waiting state because the engine can only service one active request at a time.</remarks>
void SubmitBuildRequest(BuildRequest request);
/// <summary>
/// Notifies the engine of a build result for a waiting build request.
/// </summary>
/// <param name="unblocker">The unblocking information</param>
void UnblockBuildRequest(BuildRequestUnblocker unblocker);
/// <summary>
/// Notifies the engine of a resource response granting the node resources.
/// </summary>
/// <param name="response">The resource response.</param>
void GrantResources(ResourceResponse response);
/// <summary>
/// Notifies the engine of a configuration response packet, typically generated by the Build Request Manager. This packet is used to set
/// the global configuration ID for a specific configuration.
/// </summary>
/// <param name="response">The build configuration response.</param>
void ReportConfigurationResponse(BuildRequestConfigurationResponse response);
#endregion
}
}
|