1 // Copyright (c) Microsoft. All rights reserved. 2 // Licensed under the MIT license. See LICENSE file in the project root for full license information. 3 //----------------------------------------------------------------------- 4 // </copyright> 5 // <summary>Interface for the build request engine.</summary> 6 //----------------------------------------------------------------------- 7 8 using System; 9 using System.Collections.Generic; 10 using System.Text; 11 12 using NodeLoggingContext = Microsoft.Build.BackEnd.Logging.NodeLoggingContext; 13 using BuildResult = Microsoft.Build.Execution.BuildResult; 14 15 namespace Microsoft.Build.BackEnd 16 { 17 #region Delegates 18 /// <summary> 19 /// Callback for event raised when a build request is completed 20 /// </summary> 21 /// <param name="request">The request which completed</param> 22 /// <param name="result">The result for the request</param> RequestCompleteDelegate(BuildRequest request, BuildResult result)23 internal delegate void RequestCompleteDelegate(BuildRequest request, BuildResult result); 24 25 /// <summary> 26 /// Callback for event raised when a request is resumed 27 /// </summary> 28 /// <param name="request">The request being resumed</param> RequestResumedDelegate(BuildRequest request)29 internal delegate void RequestResumedDelegate(BuildRequest request); 30 31 /// <summary> 32 /// Callback for event raised when a new build request is generated by an MSBuild callback 33 /// </summary> 34 /// <param name="blocker">Information about what is blocking the engine.</param> RequestBlockedDelegate(BuildRequestBlocker blocker)35 internal delegate void RequestBlockedDelegate(BuildRequestBlocker blocker); 36 37 /// <summary> 38 /// Callback for event raised when the build request engine's status changes. 39 /// </summary> 40 /// <param name="newStatus">The new status for the engine</param> EngineStatusChangedDelegate(BuildRequestEngineStatus newStatus)41 internal delegate void EngineStatusChangedDelegate(BuildRequestEngineStatus newStatus); 42 43 /// <summary> 44 /// Callback for event raised when a new configuration needs an ID resolved. 45 /// </summary> 46 /// <param name="config">The configuration needing an ID</param> NewConfigurationRequestDelegate(BuildRequestConfiguration config)47 internal delegate void NewConfigurationRequestDelegate(BuildRequestConfiguration config); 48 49 /// <summary> 50 /// Callback for event raised when there is an unhandled exception in the engine. 51 /// </summary> 52 /// <param name="e">The exception.</param> EngineExceptionDelegate(Exception e)53 internal delegate void EngineExceptionDelegate(Exception e); 54 55 #endregion 56 57 /// <summary> 58 /// Status types for the build request engine 59 /// </summary> 60 internal enum BuildRequestEngineStatus 61 { 62 /// <summary> 63 /// The engine has not yet been initialized, and cannot accept requests. 64 /// </summary> 65 Uninitialized, 66 67 /// <summary> 68 /// The engine has no active or waiting build requests. 69 /// </summary> 70 Idle, 71 72 /// <summary> 73 /// The engine is presently working on a build request. 74 /// </summary> 75 Active, 76 77 /// <summary> 78 /// The engine has only build requests which are waiting for build results to continue. 79 /// </summary> 80 Waiting, 81 82 /// <summary> 83 /// The engine has shut down. 84 /// </summary> 85 Shutdown 86 } 87 88 /// <summary> 89 /// Objects implementing this interface may be used by a Node to process build requests 90 /// and generate build results. 91 /// </summary> 92 internal interface IBuildRequestEngine 93 { 94 #region Events 95 /// <summary> 96 /// Raised when a build request is completed and results are available. 97 /// </summary> 98 event RequestCompleteDelegate OnRequestComplete; 99 100 /// <summary> 101 /// Raised when a build request is resumed from a previously waiting state. 102 /// </summary> 103 event RequestResumedDelegate OnRequestResumed; 104 105 /// <summary> 106 /// Raised when a new build request is generated by an MSBuild callback. 107 /// </summary> 108 event RequestBlockedDelegate OnRequestBlocked; 109 110 /// <summary> 111 /// Raised when the engine status changes. 112 /// </summary> 113 event EngineStatusChangedDelegate OnStatusChanged; 114 115 /// <summary> 116 /// Raised when a configuration needs an id. 117 /// </summary> 118 event NewConfigurationRequestDelegate OnNewConfigurationRequest; 119 120 /// <summary> 121 /// Raised when an unhandled exception occurs in the engine. 122 /// </summary> 123 event EngineExceptionDelegate OnEngineException; 124 125 #endregion 126 127 #region Properties 128 /// <summary> 129 /// Gets the current engine status. 130 /// </summary> 131 BuildRequestEngineStatus Status 132 { 133 get; 134 } 135 #endregion 136 137 #region Methods 138 /// <summary> 139 /// Prepares the engine for a new build and spins up the engine thread. 140 /// The engine must be in the Idle state, and not already be initialized. 141 /// </summary> 142 /// <param name="loggingContext">The logging context for the node.</param> InitializeForBuild(NodeLoggingContext loggingContext)143 void InitializeForBuild(NodeLoggingContext loggingContext); 144 145 /// <summary> 146 /// Cleans up after a build but leaves the engine thread running. Aborts 147 /// any outstanding requests. Blocks until the engine has cleaned up 148 /// everything. After this method is called, InitializeForBuild may be 149 /// called to start a new build, or the component may be shut down. 150 /// </summary> CleanupForBuild()151 void CleanupForBuild(); 152 153 /// <summary> 154 /// Submits the specified request to the build queue. 155 /// </summary> 156 /// <param name="request">The request to build.</param> 157 /// <remarks>It is only valid to call this method when the engine is in the Idle or 158 /// Waiting state because the engine can only service one active request at a time.</remarks> SubmitBuildRequest(BuildRequest request)159 void SubmitBuildRequest(BuildRequest request); 160 161 /// <summary> 162 /// Notifies the engine of a build result for a waiting build request. 163 /// </summary> 164 /// <param name="unblocker">The unblocking information</param> UnblockBuildRequest(BuildRequestUnblocker unblocker)165 void UnblockBuildRequest(BuildRequestUnblocker unblocker); 166 167 /// <summary> 168 /// Notifies the engine of a configuration response packet, typically generated by the Build Request Manager. This packet is used to set 169 /// the global configuration ID for a specific configuration. 170 /// </summary> 171 /// <param name="response">The build configuration response.</param> ReportConfigurationResponse(BuildRequestConfigurationResponse response)172 void ReportConfigurationResponse(BuildRequestConfigurationResponse response); 173 174 #endregion 175 } 176 } 177