ThreadPlan.h revision 88e3de205708f14431559072ca258899b5ac31cc
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#include "lldb/Target/Process.h" 22#include "lldb/Target/Target.h" 23#include "lldb/Target/Thread.h" 24#include "lldb/Target/ThreadPlanTracer.h" 25#include "lldb/Target/StopInfo.h" 26 27namespace lldb_private { 28 29//------------------------------------------------------------------ 30// ThreadPlan: 31// This is the pure virtual base class for thread plans. 32// 33// The thread plans provide the "atoms" of behavior that 34// all the logical process control, either directly from commands or through 35// more complex composite plans will rely on. 36// 37// Plan Stack: 38// 39// The thread maintaining a thread plan stack, and you program the actions of a particular thread 40// by pushing plans onto the plan stack. 41// There is always a "Current" plan, which is the head of the plan stack, though in some cases 42// a plan may defer to plans higher in the stack for some piece of information. 43// 44// The plan stack is never empty, there is always a Base Plan which persists through the life 45// of the running process. 46// 47// 48// Creating Plans: 49// 50// The thread plan is generally created and added to the plan stack through the QueueThreadPlanFor... API 51// in lldb::Thread. Those API's will return the plan that performs the named operation in a manner 52// appropriate for the current process. The plans in lldb/source/Target are generic 53// implementations, but a Process plugin can override them. 54// 55// ValidatePlan is then called. If it returns false, the plan is unshipped. This is a little 56// convenience which keeps us from having to error out of the constructor. 57// 58// Then the plan is added to the plan stack. When the plan is added to the plan stack its DidPush 59// will get called. This is useful if a plan wants to push any additional plans as it is constructed, 60// since you need to make sure you're already on the stack before you push additional plans. 61// 62// Completed Plans: 63// 64// When the target process stops the plans are queried, among other things, for whether their job is done. 65// If it is they are moved from the plan stack to the Completed Plan stack in reverse order from their position 66// on the plan stack (since multiple plans may be done at a given stop.) This is used primarily so that 67// the lldb::Thread::StopInfo for the thread can be set properly. If one plan pushes another to achieve part of 68// its job, but it doesn't want that sub-plan to be the one that sets the StopInfo, then call SetPrivate on the 69// sub-plan when you create it, and the Thread will pass over that plan in reporting the reason for the stop. 70// 71// Discarded plans: 72// 73// Your plan may also get discarded, i.e. moved from the plan stack to the "discarded plan stack". This can 74// happen, for instance, if the plan is calling a function and the function call crashes and you want 75// to unwind the attempt to call. So don't assume that your plan will always successfully stop. Which leads to: 76// 77// Cleaning up after your plans: 78// 79// When the plan is moved from the plan stack its WillPop method is always called, no matter why. Once it is 80// moved off the plan stack it is done, and won't get a chance to run again. So you should 81// undo anything that affects target state in this method. But be sure to leave the plan able to correctly 82// fill the StopInfo, however. 83// N.B. Don't wait to do clean up target state till the destructor, since that will usually get called when 84// the target resumes, and you want to leave the target state correct for new plans in the time between when 85// your plan gets unshipped and the next resume. 86// 87// Over the lifetime of the plan, various methods of the ThreadPlan are then called in response to changes of state in 88// the process we are debugging as follows: 89// 90// Resuming: 91// 92// When the target process is about to be restarted, the plan's WillResume method is called, 93// giving the plan a chance to prepare for the run. If WillResume returns false, then the 94// process is not restarted. Be sure to set an appropriate error value in the Process if 95// you have to do this. 96// Next the "StopOthers" method of all the threads are polled, and if one thread's Current plan 97// returns "true" then only that thread gets to run. If more than one returns "true" the threads that want to run solo 98// get run one by one round robin fashion. Otherwise all are let to run. 99// 100// Note, the way StopOthers is implemented, the base class implementation just asks the previous plan. So if your plan 101// has no opinion about whether it should run stopping others or not, just don't implement StopOthers, and the parent 102// will be asked. 103// 104// Finally, for each thread that is running, it run state is set to the return of RunState from the 105// thread's Current plan. 106// 107// Responding to a stop: 108// 109// When the target process stops, the plan is called in the following stages: 110// 111// First the thread asks the Current Plan if it can handle this stop by calling PlanExplainsStop. 112// If the Current plan answers "true" then it is asked if the stop should percolate all the way to the 113// user by calling the ShouldStop method. If the current plan doesn't explain the stop, then we query down 114// the plan stack for a plan that does explain the stop. The plan that does explain the stop then needs to 115// figure out what to do about the plans below it in the stack. If the stop is recoverable, then the plan that 116// understands it can just do what it needs to set up to restart, and then continue. 117// Otherwise, the plan that understood the stop should call DiscardPlanStack to clean up the stack below it. 118// 119// Master plans: 120// 121// In the normal case, when we decide to stop, we will collapse the plan stack up to the point of the plan that understood 122// the stop reason. However, if a plan wishes to stay on the stack after an event it didn't directly handle 123// it can designate itself a "Master" plan by responding true to IsMasterPlan, and then if it wants not to be 124// discarded, it can return true to OkayToDiscard, and it and all its dependent plans will be preserved when 125// we resume execution. 126// 127// The other effect of being a master plan is that when the Master plan is done , if it has set "OkayToDiscard" to false, 128// then it will be popped & execution will stop and return to the user. Remember that if OkayToDiscard is false, the 129// plan will be popped and control will be given to the next plan above it on the stack So setting OkayToDiscard to 130// false means the user will regain control when the MasterPlan is completed. 131// 132// Between these two controls this allows things like: a MasterPlan/DontDiscard Step Over to hit a breakpoint, stop and 133// return control to the user, but then when the user continues, the step out succeeds. 134// Even more tricky, when the breakpoint is hit, the user can continue to step in/step over/etc, and finally when they 135// continue, they will finish up the Step Over. 136// 137// FIXME: MasterPlan & OkayToDiscard aren't really orthogonal. MasterPlan designation means that this plan controls 138// it's fate and the fate of plans below it. OkayToDiscard tells whether the MasterPlan wants to stay on the stack. I 139// originally thought "MasterPlan-ness" would need to be a fixed characteristic of a ThreadPlan, in which case you needed 140// the extra control. But that doesn't seem to be true. So we should be able to convert to only MasterPlan status to mean 141// the current "MasterPlan/DontDiscard". Then no plans would be MasterPlans by default, and you would set the ones you 142// wanted to be "user level" in this way. 143// 144// 145// Actually Stopping: 146// 147// If a plan says responds "true" to ShouldStop, then it is asked if it's job is complete by calling 148// MischiefManaged. If that returns true, the thread is popped from the plan stack and added to the 149// Completed Plan Stack. Then the next plan in the stack is asked if it ShouldStop, and it returns "true", 150// it is asked if it is done, and if yes popped, and so on till we reach a plan that is not done. 151// 152// Since you often know in the ShouldStop method whether your plan is complete, as a convenience you can call 153// SetPlanComplete and the ThreadPlan implementation of MischiefManaged will return "true", without your having 154// to redo the calculation when your sub-classes MischiefManaged is called. If you call SetPlanComplete, you can 155// later use IsPlanComplete to determine whether the plan is complete. This is only a convenience for sub-classes, 156// the logic in lldb::Thread will only call MischiefManaged. 157// 158// One slightly tricky point is you have to be careful using SetPlanComplete in PlanExplainsStop because you 159// are not guaranteed that PlanExplainsStop for a plan will get called before ShouldStop gets called. If your sub-plan 160// explained the stop and then popped itself, only your ShouldStop will get called. 161// 162// If ShouldStop for any thread returns "true", then the WillStop method of the Current plan of 163// all threads will be called, the stop event is placed on the Process's public broadcaster, and 164// control returns to the upper layers of the debugger. 165// 166// Reporting the stop: 167// 168// When the process stops, the thread is given a StopReason, in the form of a StopInfo object. If there is a completed 169// plan corresponding to the stop, then the "actual" stop reason will be suppressed, and instead a StopInfoThreadPlan 170// object will be cons'ed up from the highest completed plan in the stack. However, if the plan doesn't want to be 171// the stop reason, then it can call SetPlanComplete and pass in "false" for the "success" parameter. In that case, 172// the real stop reason will be used instead. One exapmle of this is the "StepRangeStepIn" thread plan. If it stops 173// because of a crash or breakpoint hit, it wants to unship itself, because it isn't so useful to have step in keep going 174// after a breakpoint hit. But it can't be the reason for the stop or no-one would see that they had hit a breakpoint. 175// 176// Cleaning up the plan stack: 177// 178// One of the complications of MasterPlans is that you may get past the limits of a plan without triggering it to clean 179// itself up. For instance, if you are doing a MasterPlan StepOver, and hit a breakpoint in a called function, then 180// step over enough times to step out of the initial StepOver range, each of the step overs will explain the stop & 181// take themselves off the stack, but control would never be returned to the original StepOver. Eventually, the user 182// will continue, and when that continue stops, the old stale StepOver plan that was left on the stack will get woken 183// up and notice it is done. But that can leave junk on the stack for a while. To avoid that, the plans implement a 184// "IsPlanStale" method, that can check whether it is relevant anymore. On stop, after the regular plan negotiation, 185// the remaining plan stack is consulted and if any plan says it is stale, it and the plans below it are discarded from 186// the stack. 187// 188// Automatically Resuming: 189// 190// If ShouldStop for all threads returns "false", then the target process will resume. This then cycles back to 191// Resuming above. 192// 193// Reporting eStateStopped events when the target is restarted: 194// 195// If a plan decides to auto-continue the target by returning "false" from ShouldStop, then it will be asked 196// whether the Stopped event should still be reported. For instance, if you hit a breakpoint that is a User set 197// breakpoint, but the breakpoint callback said to continue the target process, you might still want to inform 198// the upper layers of lldb that the stop had happened. 199// The way this works is every thread gets to vote on whether to report the stop. If all votes are eVoteNoOpinion, 200// then the thread list will decide what to do (at present it will pretty much always suppress these stopped events.) 201// If there is an eVoteYes, then the event will be reported regardless of the other votes. If there is an eVoteNo 202// and no eVoteYes's, then the event won't be reported. 203// 204// One other little detail here, sometimes a plan will push another plan onto the plan stack to do some part of 205// the first plan's job, and it would be convenient to tell that plan how it should respond to ShouldReportStop. 206// You can do that by setting the stop_vote in the child plan when you create it. 207// 208// Suppressing the initial eStateRunning event: 209// 210// The private process running thread will take care of ensuring that only one "eStateRunning" event will be 211// delivered to the public Process broadcaster per public eStateStopped event. However there are some cases 212// where the public state of this process is eStateStopped, but a thread plan needs to restart the target, but 213// doesn't want the running event to be publically broadcast. The obvious example of this is running functions 214// by hand as part of expression evaluation. To suppress the running event return eVoteNo from ShouldReportStop, 215// to force a running event to be reported return eVoteYes, in general though you should return eVoteNoOpinion 216// which will allow the ThreadList to figure out the right thing to do. 217// The run_vote argument to the constructor works like stop_vote, and is a way for a plan to instruct a sub-plan 218// on how to respond to ShouldReportStop. 219// 220//------------------------------------------------------------------ 221 222class ThreadPlan : 223 public UserID 224{ 225public: 226 typedef enum 227 { 228 eAllThreads, 229 eSomeThreads, 230 eThisThread 231 } ThreadScope; 232 233 // We use these enums so that we can cast a base thread plan to it's real type without having to resort 234 // to dynamic casting. 235 typedef enum 236 { 237 eKindGeneric, 238 eKindBase, 239 eKindCallFunction, 240 eKindStepInstruction, 241 eKindStepOut, 242 eKindStepOverBreakpoint, 243 eKindStepOverRange, 244 eKindStepInRange, 245 eKindRunToAddress, 246 eKindStepThrough, 247 eKindStepUntil, 248 eKindTestCondition 249 250 } ThreadPlanKind; 251 252 //------------------------------------------------------------------ 253 // Constructors and Destructors 254 //------------------------------------------------------------------ 255 ThreadPlan (ThreadPlanKind kind, 256 const char *name, 257 Thread &thread, 258 Vote stop_vote, 259 Vote run_vote); 260 261 virtual 262 ~ThreadPlan(); 263 264 //------------------------------------------------------------------ 265 /// Returns the name of this thread plan. 266 /// 267 /// @return 268 /// A const char * pointer to the thread plan's name. 269 //------------------------------------------------------------------ 270 const char * 271 GetName () const 272 { 273 return m_name.c_str(); 274 } 275 276 //------------------------------------------------------------------ 277 /// Returns the Thread that is using this thread plan. 278 /// 279 /// @return 280 /// A pointer to the thread plan's owning thread. 281 //------------------------------------------------------------------ 282 Thread & 283 GetThread() 284 { 285 return m_thread; 286 } 287 288 const Thread & 289 GetThread() const 290 { 291 return m_thread; 292 } 293 294 Target & 295 GetTarget() 296 { 297 return m_thread.GetProcess()->GetTarget(); 298 } 299 300 const Target & 301 GetTarget() const 302 { 303 return m_thread.GetProcess()->GetTarget(); 304 } 305 306 //------------------------------------------------------------------ 307 /// Print a description of this thread to the stream \a s. 308 /// \a thread. 309 /// 310 /// @param[in] s 311 /// The stream to which to print the description. 312 /// 313 /// @param[in] level 314 /// The level of description desired. Note that eDescriptionLevelBrief 315 /// will be used in the stop message printed when the plan is complete. 316 //------------------------------------------------------------------ 317 virtual void 318 GetDescription (Stream *s, 319 lldb::DescriptionLevel level) = 0; 320 321 //------------------------------------------------------------------ 322 /// Returns whether this plan could be successfully created. 323 /// 324 /// @param[in] error 325 /// A stream to which to print some reason why the plan could not be created. 326 /// Can be NULL. 327 /// 328 /// @return 329 /// \b true if the plan should be queued, \b false otherwise. 330 //------------------------------------------------------------------ 331 virtual bool 332 ValidatePlan (Stream *error) = 0; 333 334 virtual bool 335 PlanExplainsStop () = 0; 336 337 bool 338 TracerExplainsStop () 339 { 340 if (!m_tracer_sp) 341 return false; 342 else 343 return m_tracer_sp->TracerExplainsStop(); 344 } 345 346 347 lldb::StateType 348 RunState (); 349 350 virtual bool 351 ShouldStop (Event *event_ptr) = 0; 352 353 virtual bool 354 ShouldAutoContinue (Event *event_ptr) 355 { 356 return false; 357 } 358 359 // Whether a "stop class" event should be reported to the "outside world". In general 360 // if a thread plan is active, events should not be reported. 361 362 virtual Vote 363 ShouldReportStop (Event *event_ptr); 364 365 virtual Vote 366 ShouldReportRun (Event *event_ptr); 367 368 virtual void 369 SetStopOthers (bool new_value); 370 371 virtual bool 372 StopOthers (); 373 374 virtual bool 375 WillResume (lldb::StateType resume_state, bool current_plan); 376 377 virtual bool 378 WillStop () = 0; 379 380 bool 381 IsMasterPlan() 382 { 383 return m_is_master_plan; 384 } 385 386 bool 387 SetIsMasterPlan (bool value) 388 { 389 bool old_value = m_is_master_plan; 390 m_is_master_plan = value; 391 return old_value; 392 } 393 394 virtual bool 395 OkayToDiscard(); 396 397 void 398 SetOkayToDiscard (bool value) 399 { 400 m_okay_to_discard = value; 401 } 402 403 // The base class MischiefManaged does some cleanup - so you have to call it 404 // in your MischiefManaged derived class. 405 virtual bool 406 MischiefManaged (); 407 408 bool 409 GetPrivate () 410 { 411 return m_plan_private; 412 } 413 414 void 415 SetPrivate (bool input) 416 { 417 m_plan_private = input; 418 } 419 420 virtual void 421 DidPush(); 422 423 virtual void 424 WillPop(); 425 426 // This pushes \a plan onto the plan stack of the current plan's thread. 427 void 428 PushPlan (lldb::ThreadPlanSP &thread_plan_sp) 429 { 430 m_thread.PushPlan (thread_plan_sp); 431 } 432 433 ThreadPlanKind GetKind() const 434 { 435 return m_kind; 436 } 437 438 bool 439 IsPlanComplete(); 440 441 void 442 SetPlanComplete (bool success = true); 443 444 virtual bool 445 IsPlanStale () 446 { 447 return false; 448 } 449 450 bool 451 PlanSucceeded () 452 { 453 return m_plan_succeeded; 454 } 455 456 virtual bool 457 IsBasePlan() 458 { 459 return false; 460 } 461 462 lldb::ThreadPlanTracerSP & 463 GetThreadPlanTracer() 464 { 465 return m_tracer_sp; 466 } 467 468 void 469 SetThreadPlanTracer (lldb::ThreadPlanTracerSP new_tracer_sp) 470 { 471 m_tracer_sp = new_tracer_sp; 472 } 473 474 void 475 DoTraceLog () 476 { 477 if (m_tracer_sp && m_tracer_sp->TracingEnabled()) 478 m_tracer_sp->Log(); 479 } 480 481 // Some thread plans hide away the actual stop info which caused any particular stop. For 482 // instance the ThreadPlanCallFunction restores the original stop reason so that stopping and 483 // calling a few functions won't lose the history of the run. 484 // This call can be implemented to get you back to the real stop info. 485 virtual lldb::StopInfoSP 486 GetRealStopInfo () 487 { 488 return m_thread.GetStopInfo (); 489 } 490 491 virtual lldb::ValueObjectSP 492 GetReturnValueObject () 493 { 494 return lldb::ValueObjectSP(); 495 } 496 497protected: 498 //------------------------------------------------------------------ 499 // Classes that inherit from ThreadPlan can see and modify these 500 //------------------------------------------------------------------ 501 502 // This gets the previous plan to the current plan (for forwarding requests). 503 // This is mostly a formal requirement, it allows us to make the Thread's 504 // GetPreviousPlan protected, but only friend ThreadPlan to thread. 505 506 ThreadPlan * 507 GetPreviousPlan () 508 { 509 return m_thread.GetPreviousPlan (this); 510 } 511 512 // This forwards the private Thread::GetPrivateStopReason which is generally what 513 // ThreadPlan's need to know. 514 515 lldb::StopInfoSP 516 GetPrivateStopReason() 517 { 518 return m_thread.GetPrivateStopReason (); 519 } 520 521 void 522 SetStopInfo (lldb::StopInfoSP stop_reason_sp) 523 { 524 m_thread.SetStopInfo (stop_reason_sp); 525 } 526 527 virtual lldb::StateType 528 GetPlanRunState () = 0; 529 530 Thread &m_thread; 531 Vote m_stop_vote; 532 Vote m_run_vote; 533 534private: 535 //------------------------------------------------------------------ 536 // For ThreadPlan only 537 //------------------------------------------------------------------ 538 static lldb::user_id_t GetNextID (); 539 540 ThreadPlanKind m_kind; 541 std::string m_name; 542 Mutex m_plan_complete_mutex; 543 bool m_plan_complete; 544 bool m_plan_private; 545 bool m_okay_to_discard; 546 bool m_is_master_plan; 547 bool m_plan_succeeded; 548 549 lldb::ThreadPlanTracerSP m_tracer_sp; 550 551private: 552 DISALLOW_COPY_AND_ASSIGN(ThreadPlan); 553}; 554 555 556} // namespace lldb_private 557 558#endif // liblldb_ThreadPlan_h_ 559