ThreadPlan.h revision 9dd6edde116d93777dae51ec550dee741019487e
1//===-- ThreadPlan.h --------------------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef liblldb_ThreadPlan_h_ 11#define liblldb_ThreadPlan_h_ 12 13// C Includes 14// C++ Includes 15#include <string> 16// Other libraries and framework includes 17// Project includes 18#include "lldb/lldb-private.h" 19#include "lldb/Core/UserID.h" 20#include "lldb/Host/Mutex.h" 21 22namespace lldb_private { 23 24//------------------------------------------------------------------ 25// ThreadPlan: 26// This is the pure virtual base class for thread plans. 27// 28// The thread plans provide the "atoms" of behavior that 29// all the logical process control, either directly from commands or through 30// more complex composite plans will rely on. 31// 32// Plan Stack: 33// 34// The thread maintaining a thread plan stack, and you program the actions of a particular thread 35// by pushing plans onto the plan stack. 36// There is always a "Current" plan, which is the head of the plan stack, though in some cases 37// a plan may defer to plans higher in the stack for some piece of information. 38// 39// The plan stack is never empty, there is always a Base Plan which persists through the life 40// of the running process. 41// 42// 43// DEPRECATED: This ended up causing a real hassle, too many cases where the immediate plan 44// got stranded. So the better way to do this is to post any plans you need to do right before 45// running in the PrepareToResume method. 46//f 47// Immediate Plans: 48// 49// One other complexity of the plan stack is that sometimes you need to do a piece of work immediately 50// on resume, regardless of what other plans have been pushed on the stack while the process has 51// been stopped. The classic example is stepping over a breakpoint. To that end the plan stack is 52// actually two stacks, an "immediate" plan stack and the normal plan stack. A plan can indicate that it 53// should go on the immediate plan stack by returning "true" from the IsImmediate method. 54// 55// END DEPRECATED... 56// 57// Creating Plans: 58// 59// The thread plan is generally created and added to the plan stack through the QueueThreadPlanFor... API 60// in lldb::Thread. Those API's will return the plan that performs the named operation in a manner 61// appropriate for the current process. The plans in lldb/source/Target are generic 62// implementations, but a Process plugin can override them. 63// 64// ValidatePlan is then called. If it returns false, the plan is unshipped. This is a little 65// convenience which keeps us from having to error out of the constructor. 66// 67// Then the plan is added to the plan stack. When the plan is added to the plan stack its DidPush 68// will get called. This is useful if a plan wants to push any additional plans as it is constructed, 69// since you need to make sure you're already on the stack before you push additional plans. 70// 71// Completed Plans: 72// 73// When the target process stops the plans are queried, among other things, for whether their job is done. 74// If it is they are moved from the plan stack to the Completed Plan stack in reverse order from their position 75// on the plan stack (since multiple plans may be done at a given stop.) This is used primarily so that 76// the lldb::Thread::StopInfo for the thread can be set properly. If one plan pushes another to achieve part of 77// its job, but it doesn't want that sub-plan to be the one that sets the StopInfo, then call SetPrivate on the 78// sub-plan when you create it, and the Thread will pass over that plan in reporting the reason for the stop. 79// 80// When the plan is moved from the plan stack to the completed plan stack its DidPop method is called. You should 81// undo anything that affects target state in this method so the target state is clear for new plans. 82// But be sure to leave whatever state might be needed to correctly fill the StopInfo. 83// 84// Over the lifetime of the plan, various methods of the ThreadPlan are then called in response to changes of state in 85// the process we are debugging as follows: 86// 87// Resuming: 88// 89// When the target process is about to be restarted, the plan's WillResume method is called, 90// giving the plan a chance to prepare for the run. If WillResume returns false, then the 91// process is not restarted. Be sure to set an appropriate error value in the Process if 92// you have to do this. 93// Next the "StopOthers" method of all the threads are polled, and if one thread's Current plan 94// returns "true" then only that thread gets to run. If more than one returns "true" the threads that want to run solo 95// get run one by one round robin fashion. Otherwise all are let to run. 96// Finally, for each thread that is running, it run state is set to the return of RunState from the 97// thread's Current plan. 98// 99// Responding to a stop: 100// 101// When the target process stops, the plan is called in the following stages: 102// 103// First the thread asks the Current Plan if it can handle this stop by calling PlanExplainsStop. 104// If the Current plan answers "true" then it is asked if the stop should percolate all the way to the 105// user by calling the ShouldStop method. If the current plan doesn't explain the stop, then we query down 106// the plan stack for a plan that does explain the stop. The plan that does explain the stop then needs to 107// figure out what to do about the plans below it in the stack. If the stop is recoverable, then the plan that 108// understands it can just do what it needs to set up to restart, and then continue. 109// Otherwise, the plan that understood the stop should call DiscardPlanStack to clean up the stack below it. 110// In the normal case, this will just collapse the plan stack up to the point of the plan that understood 111// the stop reason. However, if a plan wishes to stay on the stack after an event it didn't directly handle 112// it can designate itself a "Master" plan by responding true to IsMasterPlan, and then if it wants not to be 113// discarded, it can return true to OkayToDiscard, and it and all its dependent plans will be preserved when 114// we resume execution. 115// 116// Actually Stopping: 117// 118// If a plan says responds "true" to ShouldStop, then it is asked if it's job is complete by calling 119// MischiefManaged. If that returns true, the thread is popped from the plan stack and added to the 120// Completed Plan Stack. Then the next plan in the stack is asked if it ShouldStop, and it returns "true", 121// it is asked if it is done, and if yes popped, and so on till we reach a plan that is not done. 122// 123// Since you often know in the ShouldStop method whether your plan is complete, as a convenience you can call 124// SetPlanComplete and the ThreadPlan implementation of MischiefManaged will return "true", without your having 125// to redo the calculation when your sub-classes MischiefManaged is called. If you call SetPlanComplete, you can 126// later use IsPlanComplete to determine whether the plan is complete. This is only a convenience for sub-classes, 127// the logic in lldb::Thread will only call MischiefManaged. 128// 129// One slightly tricky point is you have to be careful using SetPlanComplete in PlanExplainsStop because you 130// are not guaranteed that PlanExplainsStop for a plan will get called before ShouldStop gets called. If your sub-plan 131// explained the stop and then popped itself, only your ShouldStop will get called. 132// 133// If ShouldStop for any thread returns "true", then the WillStop method of the Current plan of 134// all threads will be called, the stop event is placed on the Process's public broadcaster, and 135// control returns to the upper layers of the debugger. 136// 137// Automatically Resuming: 138// 139// If ShouldStop for all threads returns "false", then the target process will resume. This then cycles back to 140// Resuming above. 141// 142// Reporting eStateStopped events when the target is restarted: 143// 144// If a plan decides to auto-continue the target by returning "false" from ShouldStop, then it will be asked 145// whether the Stopped event should still be reported. For instance, if you hit a breakpoint that is a User set 146// breakpoint, but the breakpoint callback said to continue the target process, you might still want to inform 147// the upper layers of lldb that the stop had happened. 148// The way this works is every thread gets to vote on whether to report the stop. If all votes are eVoteNoOpinion, 149// then the thread list will decide what to do (at present it will pretty much always suppress these stopped events.) 150// If there is an eVoteYes, then the event will be reported regardless of the other votes. If there is an eVoteNo 151// and no eVoteYes's, then the event won't be reported. 152// 153// One other little detail here, sometimes a plan will push another plan onto the plan stack to do some part of 154// the first plan's job, and it would be convenient to tell that plan how it should respond to ShouldReportStop. 155// You can do that by setting the stop_vote in the child plan when you create it. 156// 157// Suppressing the initial eStateRunning event: 158// 159// The private process running thread will take care of ensuring that only one "eStateRunning" event will be 160// delivered to the public Process broadcaster per public eStateStopped event. However there are some cases 161// where the public state of this process is eStateStopped, but a thread plan needs to restart the target, but 162// doesn't want the running event to be publically broadcast. The obvious example of this is running functions 163// by hand as part of expression evaluation. To suppress the running event return eVoteNo from ShouldReportStop, 164// to force a running event to be reported return eVoteYes, in general though you should return eVoteNoOpinion 165// which will allow the ThreadList to figure out the right thing to do. 166// The run_vote argument to the constructor works like stop_vote, and is a way for a plan to instruct a sub-plan 167// on how to respond to ShouldReportStop. 168// 169//------------------------------------------------------------------ 170 171class ThreadPlan: 172 public UserID 173{ 174public: 175 typedef enum 176 { 177 eAllThreads, 178 eSomeThreads, 179 eThisThread 180 } ThreadScope; 181 182 //------------------------------------------------------------------ 183 // Constructors and Destructors 184 //------------------------------------------------------------------ 185 ThreadPlan (const char *name, 186 Thread &thread, 187 lldb::Vote stop_vote, 188 lldb::Vote run_vote); 189 190 virtual 191 ~ThreadPlan(); 192 193 //------------------------------------------------------------------ 194 /// Returns the name of this thread plan. 195 /// 196 /// @return 197 /// A const char * pointer to the thread plan's name. 198 //------------------------------------------------------------------ 199 const char * 200 GetName () const; 201 202 //------------------------------------------------------------------ 203 /// Returns the Thread that is using this thread plan. 204 /// 205 /// @return 206 /// A pointer to the thread plan's owning thread. 207 //------------------------------------------------------------------ 208 Thread & 209 GetThread(); 210 211 const Thread & 212 GetThread() const; 213 214 //------------------------------------------------------------------ 215 /// Print a description of this thread to the stream \a s. 216 /// \a thread. 217 /// 218 /// @param[in] s 219 /// The stream to which to print the description. 220 /// 221 /// @param[in] level 222 /// The level of description desired. Note that eDescriptionLevelBrief 223 /// will be used in the stop message printed when the plan is complete. 224 //------------------------------------------------------------------ 225 virtual void 226 GetDescription (Stream *s, 227 lldb::DescriptionLevel level) = 0; 228 229 //------------------------------------------------------------------ 230 /// Returns whether this plan needs to be executed immediatly on resume. 231 /// 232 /// @return 233 /// \b true if the plan is immediate, \b false otherwise. 234 //------------------------------------------------------------------ 235 virtual bool 236 IsImmediate() const 237 { 238 return false; 239 } 240 241 //------------------------------------------------------------------ 242 /// Returns whether this plan could be successfully created. 243 /// 244 /// @param[in] error 245 /// A stream to which to print some reason why the plan could not be created. 246 /// 247 /// @return 248 /// \b true if the plan should be queued, \b false otherwise. 249 //------------------------------------------------------------------ 250 virtual bool 251 ValidatePlan (Stream *error) = 0; 252 253 virtual bool 254 PlanExplainsStop () = 0; 255 256 257 virtual lldb::StateType 258 RunState () = 0; 259 260 virtual bool 261 ShouldStop (Event *event_ptr) = 0; 262 263 // Whether a "stop class" event should be reported to the "outside world". In general 264 // if a thread plan is active, events should not be reported. 265 266 virtual lldb::Vote 267 ShouldReportStop (Event *event_ptr); 268 269 virtual lldb::Vote 270 ShouldReportRun (Event *event_ptr); 271 272 virtual bool 273 StopOthers (); 274 275 virtual bool 276 WillResume (lldb::StateType resume_state, bool current_plan); 277 278 virtual bool 279 WillStop () = 0; 280 281 virtual bool 282 IsMasterPlan() 283 { 284 return false; 285 } 286 287 virtual bool 288 OkayToDiscard(); 289 290 void 291 SetOkayToDiscard (bool value) 292 { 293 m_okay_to_discard = value; 294 } 295 296 // The base class MischiefManaged does some cleanup - so you have to call it 297 // in your MischiefManaged derived class. 298 virtual bool 299 MischiefManaged (); 300 301 bool 302 GetPrivate (); 303 304 void 305 SetPrivate (bool input); 306 307 virtual void 308 DidPush(); 309 310 virtual void 311 WillPop(); 312 313 // This pushes \a plan onto the plan stack of the current plan's thread. 314 void 315 PushPlan (lldb::ThreadPlanSP &thread_plan_sp); 316 317protected: 318 //------------------------------------------------------------------ 319 // Classes that inherit from ThreadPlan can see and modify these 320 //------------------------------------------------------------------ 321 322 bool 323 IsPlanComplete(); 324 325 void 326 SetPlanComplete (); 327 328 // This gets the previous plan to the current plan (for forwarding requests). 329 // This is mostly a formal requirement, it allows us to make the Thread's 330 // GetPreviousPlan protected, but only friend ThreadPlan to thread. 331 332 ThreadPlan * 333 GetPreviousPlan (); 334 335 Thread &m_thread; 336 lldb::Vote m_stop_vote; 337 lldb::Vote m_run_vote; 338 339private: 340 //------------------------------------------------------------------ 341 // For ThreadPlan only 342 //------------------------------------------------------------------ 343 static lldb::user_id_t GetNextID (); 344 345 std::string m_name; 346 Mutex m_plan_complete_mutex; 347 bool m_plan_complete; 348 bool m_plan_private; 349 bool m_okay_to_discard; 350 351private: 352 DISALLOW_COPY_AND_ASSIGN(ThreadPlan); 353}; 354 355 356} // namespace lldb_private 357 358#endif // liblldb_ThreadPlan_h_ 359