ThreadPlan.h revision 707b7a858ce66b15d01177d4a38ff1ccde44f43c
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// In the normal case, this will just collapse the plan stack up to the point of the plan that understood 119// the stop reason. However, if a plan wishes to stay on the stack after an event it didn't directly handle 120// it can designate itself a "Master" plan by responding true to IsMasterPlan, and then if it wants not to be 121// discarded, it can return true to OkayToDiscard, and it and all its dependent plans will be preserved when 122// we resume execution. 123// 124// Actually Stopping: 125// 126// If a plan says responds "true" to ShouldStop, then it is asked if it's job is complete by calling 127// MischiefManaged. If that returns true, the thread is popped from the plan stack and added to the 128// Completed Plan Stack. Then the next plan in the stack is asked if it ShouldStop, and it returns "true", 129// it is asked if it is done, and if yes popped, and so on till we reach a plan that is not done. 130// 131// Since you often know in the ShouldStop method whether your plan is complete, as a convenience you can call 132// SetPlanComplete and the ThreadPlan implementation of MischiefManaged will return "true", without your having 133// to redo the calculation when your sub-classes MischiefManaged is called. If you call SetPlanComplete, you can 134// later use IsPlanComplete to determine whether the plan is complete. This is only a convenience for sub-classes, 135// the logic in lldb::Thread will only call MischiefManaged. 136// 137// One slightly tricky point is you have to be careful using SetPlanComplete in PlanExplainsStop because you 138// are not guaranteed that PlanExplainsStop for a plan will get called before ShouldStop gets called. If your sub-plan 139// explained the stop and then popped itself, only your ShouldStop will get called. 140// 141// If ShouldStop for any thread returns "true", then the WillStop method of the Current plan of 142// all threads will be called, the stop event is placed on the Process's public broadcaster, and 143// control returns to the upper layers of the debugger. 144// 145// Reporting the stop: 146// 147// When the process stops, the thread is given a StopReason, in the form of a StopInfo object. If there is a completed 148// plan corresponding to the stop, then the "actual" stop reason will be suppressed, and instead a StopInfoThreadPlan 149// object will be cons'ed up from the highest completed plan in the stack. However, if the plan doesn't want to be 150// the stop reason, then it can call SetPlanComplete and pass in "false" for the "success" parameter. In that case, 151// the real stop reason will be used instead. One exapmle of this is the "StepRangeStepIn" thread plan. If it stops 152// because of a crash or breakpoint hit, it wants to unship itself, because it isn't so useful to have step in keep going 153// 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. 154// 155// Automatically Resuming: 156// 157// If ShouldStop for all threads returns "false", then the target process will resume. This then cycles back to 158// Resuming above. 159// 160// Reporting eStateStopped events when the target is restarted: 161// 162// If a plan decides to auto-continue the target by returning "false" from ShouldStop, then it will be asked 163// whether the Stopped event should still be reported. For instance, if you hit a breakpoint that is a User set 164// breakpoint, but the breakpoint callback said to continue the target process, you might still want to inform 165// the upper layers of lldb that the stop had happened. 166// The way this works is every thread gets to vote on whether to report the stop. If all votes are eVoteNoOpinion, 167// then the thread list will decide what to do (at present it will pretty much always suppress these stopped events.) 168// If there is an eVoteYes, then the event will be reported regardless of the other votes. If there is an eVoteNo 169// and no eVoteYes's, then the event won't be reported. 170// 171// One other little detail here, sometimes a plan will push another plan onto the plan stack to do some part of 172// the first plan's job, and it would be convenient to tell that plan how it should respond to ShouldReportStop. 173// You can do that by setting the stop_vote in the child plan when you create it. 174// 175// Suppressing the initial eStateRunning event: 176// 177// The private process running thread will take care of ensuring that only one "eStateRunning" event will be 178// delivered to the public Process broadcaster per public eStateStopped event. However there are some cases 179// where the public state of this process is eStateStopped, but a thread plan needs to restart the target, but 180// doesn't want the running event to be publically broadcast. The obvious example of this is running functions 181// by hand as part of expression evaluation. To suppress the running event return eVoteNo from ShouldReportStop, 182// to force a running event to be reported return eVoteYes, in general though you should return eVoteNoOpinion 183// which will allow the ThreadList to figure out the right thing to do. 184// The run_vote argument to the constructor works like stop_vote, and is a way for a plan to instruct a sub-plan 185// on how to respond to ShouldReportStop. 186// 187//------------------------------------------------------------------ 188 189class ThreadPlan : 190 public UserID 191{ 192public: 193 typedef enum 194 { 195 eAllThreads, 196 eSomeThreads, 197 eThisThread 198 } ThreadScope; 199 200 // We use these enums so that we can cast a base thread plan to it's real type without having to resort 201 // to dynamic casting. 202 typedef enum 203 { 204 eKindGeneric, 205 eKindBase, 206 eKindCallFunction, 207 eKindStepInstruction, 208 eKindStepOut, 209 eKindStepOverBreakpoint, 210 eKindStepOverRange, 211 eKindStepInRange, 212 eKindRunToAddress, 213 eKindStepThrough, 214 eKindStepUntil, 215 eKindTestCondition 216 217 } ThreadPlanKind; 218 219 //------------------------------------------------------------------ 220 // Constructors and Destructors 221 //------------------------------------------------------------------ 222 ThreadPlan (ThreadPlanKind kind, 223 const char *name, 224 Thread &thread, 225 Vote stop_vote, 226 Vote run_vote); 227 228 virtual 229 ~ThreadPlan(); 230 231 //------------------------------------------------------------------ 232 /// Returns the name of this thread plan. 233 /// 234 /// @return 235 /// A const char * pointer to the thread plan's name. 236 //------------------------------------------------------------------ 237 const char * 238 GetName () const 239 { 240 return m_name.c_str(); 241 } 242 243 //------------------------------------------------------------------ 244 /// Returns the Thread that is using this thread plan. 245 /// 246 /// @return 247 /// A pointer to the thread plan's owning thread. 248 //------------------------------------------------------------------ 249 Thread & 250 GetThread() 251 { 252 return m_thread; 253 } 254 255 const Thread & 256 GetThread() const 257 { 258 return m_thread; 259 } 260 261 Target & 262 GetTarget() 263 { 264 return m_thread.GetProcess()->GetTarget(); 265 } 266 267 const Target & 268 GetTarget() const 269 { 270 return m_thread.GetProcess()->GetTarget(); 271 } 272 273 //------------------------------------------------------------------ 274 /// Print a description of this thread to the stream \a s. 275 /// \a thread. 276 /// 277 /// @param[in] s 278 /// The stream to which to print the description. 279 /// 280 /// @param[in] level 281 /// The level of description desired. Note that eDescriptionLevelBrief 282 /// will be used in the stop message printed when the plan is complete. 283 //------------------------------------------------------------------ 284 virtual void 285 GetDescription (Stream *s, 286 lldb::DescriptionLevel level) = 0; 287 288 //------------------------------------------------------------------ 289 /// Returns whether this plan could be successfully created. 290 /// 291 /// @param[in] error 292 /// A stream to which to print some reason why the plan could not be created. 293 /// Can be NULL. 294 /// 295 /// @return 296 /// \b true if the plan should be queued, \b false otherwise. 297 //------------------------------------------------------------------ 298 virtual bool 299 ValidatePlan (Stream *error) = 0; 300 301 virtual bool 302 PlanExplainsStop () = 0; 303 304 bool 305 TracerExplainsStop () 306 { 307 if (!m_tracer_sp) 308 return false; 309 else 310 return m_tracer_sp->TracerExplainsStop(); 311 } 312 313 314 lldb::StateType 315 RunState (); 316 317 virtual bool 318 ShouldStop (Event *event_ptr) = 0; 319 320 virtual bool 321 ShouldAutoContinue (Event *event_ptr) 322 { 323 return false; 324 } 325 326 // Whether a "stop class" event should be reported to the "outside world". In general 327 // if a thread plan is active, events should not be reported. 328 329 virtual Vote 330 ShouldReportStop (Event *event_ptr); 331 332 virtual Vote 333 ShouldReportRun (Event *event_ptr); 334 335 virtual void 336 SetStopOthers (bool new_value); 337 338 virtual bool 339 StopOthers (); 340 341 virtual bool 342 WillResume (lldb::StateType resume_state, bool current_plan); 343 344 virtual bool 345 WillStop () = 0; 346 347 bool 348 IsMasterPlan() 349 { 350 return m_is_master_plan; 351 } 352 353 bool 354 SetIsMasterPlan (bool value) 355 { 356 bool old_value = m_is_master_plan; 357 m_is_master_plan = value; 358 return old_value; 359 } 360 361 virtual bool 362 OkayToDiscard(); 363 364 void 365 SetOkayToDiscard (bool value) 366 { 367 m_okay_to_discard = value; 368 } 369 370 // The base class MischiefManaged does some cleanup - so you have to call it 371 // in your MischiefManaged derived class. 372 virtual bool 373 MischiefManaged (); 374 375 bool 376 GetPrivate () 377 { 378 return m_plan_private; 379 } 380 381 void 382 SetPrivate (bool input) 383 { 384 m_plan_private = input; 385 } 386 387 virtual void 388 DidPush(); 389 390 virtual void 391 WillPop(); 392 393 // This pushes \a plan onto the plan stack of the current plan's thread. 394 void 395 PushPlan (lldb::ThreadPlanSP &thread_plan_sp) 396 { 397 m_thread.PushPlan (thread_plan_sp); 398 } 399 400 ThreadPlanKind GetKind() const 401 { 402 return m_kind; 403 } 404 405 bool 406 IsPlanComplete(); 407 408 void 409 SetPlanComplete (bool success = true); 410 411 bool 412 PlanSucceeded () 413 { 414 return m_plan_succeeded; 415 } 416 417 virtual bool 418 IsBasePlan() 419 { 420 return false; 421 } 422 423 lldb::ThreadPlanTracerSP & 424 GetThreadPlanTracer() 425 { 426 return m_tracer_sp; 427 } 428 429 void 430 SetThreadPlanTracer (lldb::ThreadPlanTracerSP new_tracer_sp) 431 { 432 m_tracer_sp = new_tracer_sp; 433 } 434 435 void 436 DoTraceLog () 437 { 438 if (m_tracer_sp && m_tracer_sp->TracingEnabled()) 439 m_tracer_sp->Log(); 440 } 441 442 // Some thread plans hide away the actual stop info which caused any particular stop. For 443 // instance the ThreadPlanCallFunction restores the original stop reason so that stopping and 444 // calling a few functions won't lose the history of the run. 445 // This call can be implemented to get you back to the real stop info. 446 virtual lldb::StopInfoSP 447 GetRealStopInfo () 448 { 449 return m_thread.GetStopInfo (); 450 } 451 452 virtual lldb::ValueObjectSP 453 GetReturnValueObject () 454 { 455 return lldb::ValueObjectSP(); 456 } 457 458protected: 459 //------------------------------------------------------------------ 460 // Classes that inherit from ThreadPlan can see and modify these 461 //------------------------------------------------------------------ 462 463 // This gets the previous plan to the current plan (for forwarding requests). 464 // This is mostly a formal requirement, it allows us to make the Thread's 465 // GetPreviousPlan protected, but only friend ThreadPlan to thread. 466 467 ThreadPlan * 468 GetPreviousPlan () 469 { 470 return m_thread.GetPreviousPlan (this); 471 } 472 473 // This forwards the private Thread::GetPrivateStopReason which is generally what 474 // ThreadPlan's need to know. 475 476 lldb::StopInfoSP 477 GetPrivateStopReason() 478 { 479 return m_thread.GetPrivateStopReason (); 480 } 481 482 void 483 SetStopInfo (lldb::StopInfoSP stop_reason_sp) 484 { 485 m_thread.SetStopInfo (stop_reason_sp); 486 } 487 488 virtual lldb::StateType 489 GetPlanRunState () = 0; 490 491 Thread &m_thread; 492 Vote m_stop_vote; 493 Vote m_run_vote; 494 495private: 496 //------------------------------------------------------------------ 497 // For ThreadPlan only 498 //------------------------------------------------------------------ 499 static lldb::user_id_t GetNextID (); 500 501 ThreadPlanKind m_kind; 502 std::string m_name; 503 Mutex m_plan_complete_mutex; 504 bool m_plan_complete; 505 bool m_plan_private; 506 bool m_okay_to_discard; 507 bool m_is_master_plan; 508 bool m_plan_succeeded; 509 510 lldb::ThreadPlanTracerSP m_tracer_sp; 511 512private: 513 DISALLOW_COPY_AND_ASSIGN(ThreadPlan); 514}; 515 516 517} // namespace lldb_private 518 519#endif // liblldb_ThreadPlan_h_ 520