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