1 //===-- ThreadPlan.h --------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ThreadPlan_h_
11 #define liblldb_ThreadPlan_h_
16 // Other libraries and framework 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"
27 namespace lldb_private {
29 //------------------------------------------------------------------
31 // This is the pure virtual base class for thread plans.
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.
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.
44 // The plan stack is never empty, there is always a Base Plan which persists through the life
45 // of the running process.
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.
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.
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.
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.
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:
77 // Cleaning up after your plans:
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.
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:
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. Note, ThreadPlans actually implement DoWillResume, WillResume wraps that call.
97 // Next the "StopOthers" method of all the threads are polled, and if one thread's Current plan
98 // returns "true" then only that thread gets to run. If more than one returns "true" the threads that want to run solo
99 // get run one by one round robin fashion. Otherwise all are let to run.
101 // Note, the way StopOthers is implemented, the base class implementation just asks the previous plan. So if your plan
102 // has no opinion about whether it should run stopping others or not, just don't implement StopOthers, and the parent
105 // Finally, for each thread that is running, it run state is set to the return of RunState from the
106 // thread's Current plan.
108 // Responding to a stop:
110 // When the target process stops, the plan is called in the following stages:
112 // First the thread asks the Current Plan if it can handle this stop by calling PlanExplainsStop.
113 // If the Current plan answers "true" then it is asked if the stop should percolate all the way to the
114 // user by calling the ShouldStop method. If the current plan doesn't explain the stop, then we query down
115 // the plan stack for a plan that does explain the stop. The plan that does explain the stop then needs to
116 // figure out what to do about the plans below it in the stack. If the stop is recoverable, then the plan that
117 // understands it can just do what it needs to set up to restart, and then continue.
118 // Otherwise, the plan that understood the stop should call DiscardPlanStack to clean up the stack below it.
119 // Note, plans actually implement DoPlanExplainsStop, the result is cached in PlanExplainsStop so the DoPlanExplainsStop
120 // itself will only get called once per stop.
124 // In the normal case, when we decide to stop, we will collapse the plan stack up to the point of the plan that understood
125 // the stop reason. However, if a plan wishes to stay on the stack after an event it didn't directly handle
126 // it can designate itself a "Master" plan by responding true to IsMasterPlan, and then if it wants not to be
127 // discarded, it can return true to OkayToDiscard, and it and all its dependent plans will be preserved when
128 // we resume execution.
130 // The other effect of being a master plan is that when the Master plan is done , if it has set "OkayToDiscard" to false,
131 // then it will be popped & execution will stop and return to the user. Remember that if OkayToDiscard is false, the
132 // plan will be popped and control will be given to the next plan above it on the stack So setting OkayToDiscard to
133 // false means the user will regain control when the MasterPlan is completed.
135 // Between these two controls this allows things like: a MasterPlan/DontDiscard Step Over to hit a breakpoint, stop and
136 // return control to the user, but then when the user continues, the step out succeeds.
137 // Even more tricky, when the breakpoint is hit, the user can continue to step in/step over/etc, and finally when they
138 // continue, they will finish up the Step Over.
140 // FIXME: MasterPlan & OkayToDiscard aren't really orthogonal. MasterPlan designation means that this plan controls
141 // it's fate and the fate of plans below it. OkayToDiscard tells whether the MasterPlan wants to stay on the stack. I
142 // originally thought "MasterPlan-ness" would need to be a fixed characteristic of a ThreadPlan, in which case you needed
143 // the extra control. But that doesn't seem to be true. So we should be able to convert to only MasterPlan status to mean
144 // the current "MasterPlan/DontDiscard". Then no plans would be MasterPlans by default, and you would set the ones you
145 // wanted to be "user level" in this way.
148 // Actually Stopping:
150 // If a plan says responds "true" to ShouldStop, then it is asked if it's job is complete by calling
151 // MischiefManaged. If that returns true, the thread is popped from the plan stack and added to the
152 // Completed Plan Stack. Then the next plan in the stack is asked if it ShouldStop, and it returns "true",
153 // it is asked if it is done, and if yes popped, and so on till we reach a plan that is not done.
155 // Since you often know in the ShouldStop method whether your plan is complete, as a convenience you can call
156 // SetPlanComplete and the ThreadPlan implementation of MischiefManaged will return "true", without your having
157 // to redo the calculation when your sub-classes MischiefManaged is called. If you call SetPlanComplete, you can
158 // later use IsPlanComplete to determine whether the plan is complete. This is only a convenience for sub-classes,
159 // the logic in lldb::Thread will only call MischiefManaged.
161 // One slightly tricky point is you have to be careful using SetPlanComplete in PlanExplainsStop because you
162 // are not guaranteed that PlanExplainsStop for a plan will get called before ShouldStop gets called. If your sub-plan
163 // explained the stop and then popped itself, only your ShouldStop will get called.
165 // If ShouldStop for any thread returns "true", then the WillStop method of the Current plan of
166 // all threads will be called, the stop event is placed on the Process's public broadcaster, and
167 // control returns to the upper layers of the debugger.
169 // Reporting the stop:
171 // When the process stops, the thread is given a StopReason, in the form of a StopInfo object. If there is a completed
172 // plan corresponding to the stop, then the "actual" stop reason will be suppressed, and instead a StopInfoThreadPlan
173 // object will be cons'ed up from the highest completed plan in the stack. However, if the plan doesn't want to be
174 // the stop reason, then it can call SetPlanComplete and pass in "false" for the "success" parameter. In that case,
175 // the real stop reason will be used instead. One exapmle of this is the "StepRangeStepIn" thread plan. If it stops
176 // because of a crash or breakpoint hit, it wants to unship itself, because it isn't so useful to have step in keep going
177 // 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.
179 // Cleaning up the plan stack:
181 // One of the complications of MasterPlans is that you may get past the limits of a plan without triggering it to clean
182 // itself up. For instance, if you are doing a MasterPlan StepOver, and hit a breakpoint in a called function, then
183 // step over enough times to step out of the initial StepOver range, each of the step overs will explain the stop &
184 // take themselves off the stack, but control would never be returned to the original StepOver. Eventually, the user
185 // will continue, and when that continue stops, the old stale StepOver plan that was left on the stack will get woken
186 // up and notice it is done. But that can leave junk on the stack for a while. To avoid that, the plans implement a
187 // "IsPlanStale" method, that can check whether it is relevant anymore. On stop, after the regular plan negotiation,
188 // the remaining plan stack is consulted and if any plan says it is stale, it and the plans below it are discarded from
191 // Automatically Resuming:
193 // If ShouldStop for all threads returns "false", then the target process will resume. This then cycles back to
196 // Reporting eStateStopped events when the target is restarted:
198 // If a plan decides to auto-continue the target by returning "false" from ShouldStop, then it will be asked
199 // whether the Stopped event should still be reported. For instance, if you hit a breakpoint that is a User set
200 // breakpoint, but the breakpoint callback said to continue the target process, you might still want to inform
201 // the upper layers of lldb that the stop had happened.
202 // The way this works is every thread gets to vote on whether to report the stop. If all votes are eVoteNoOpinion,
203 // then the thread list will decide what to do (at present it will pretty much always suppress these stopped events.)
204 // If there is an eVoteYes, then the event will be reported regardless of the other votes. If there is an eVoteNo
205 // and no eVoteYes's, then the event won't be reported.
207 // One other little detail here, sometimes a plan will push another plan onto the plan stack to do some part of
208 // the first plan's job, and it would be convenient to tell that plan how it should respond to ShouldReportStop.
209 // You can do that by setting the stop_vote in the child plan when you create it.
211 // Suppressing the initial eStateRunning event:
213 // The private process running thread will take care of ensuring that only one "eStateRunning" event will be
214 // delivered to the public Process broadcaster per public eStateStopped event. However there are some cases
215 // where the public state of this process is eStateStopped, but a thread plan needs to restart the target, but
216 // doesn't want the running event to be publically broadcast. The obvious example of this is running functions
217 // by hand as part of expression evaluation. To suppress the running event return eVoteNo from ShouldReportStop,
218 // to force a running event to be reported return eVoteYes, in general though you should return eVoteNoOpinion
219 // which will allow the ThreadList to figure out the right thing to do.
220 // The run_vote argument to the constructor works like stop_vote, and is a way for a plan to instruct a sub-plan
221 // on how to respond to ShouldReportStop.
223 //------------------------------------------------------------------
236 // We use these enums so that we can cast a base thread plan to it's real type without having to resort
237 // to dynamic casting.
244 eKindStepInstruction,
246 eKindStepOverBreakpoint,
256 //------------------------------------------------------------------
257 // Constructors and Destructors
258 //------------------------------------------------------------------
259 ThreadPlan (ThreadPlanKind kind,
268 //------------------------------------------------------------------
269 /// Returns the name of this thread plan.
272 /// A const char * pointer to the thread plan's name.
273 //------------------------------------------------------------------
277 return m_name.c_str();
280 //------------------------------------------------------------------
281 /// Returns the Thread that is using this thread plan.
284 /// A pointer to the thread plan's owning thread.
285 //------------------------------------------------------------------
301 return m_thread.GetProcess()->GetTarget();
307 return m_thread.GetProcess()->GetTarget();
310 //------------------------------------------------------------------
311 /// Print a description of this thread to the stream \a s.
315 /// The stream to which to print the description.
318 /// The level of description desired. Note that eDescriptionLevelBrief
319 /// will be used in the stop message printed when the plan is complete.
320 //------------------------------------------------------------------
322 GetDescription (Stream *s,
323 lldb::DescriptionLevel level) = 0;
325 //------------------------------------------------------------------
326 /// Returns whether this plan could be successfully created.
329 /// A stream to which to print some reason why the plan could not be created.
333 /// \b true if the plan should be queued, \b false otherwise.
334 //------------------------------------------------------------------
336 ValidatePlan (Stream *error) = 0;
339 TracerExplainsStop ()
344 return m_tracer_sp->TracerExplainsStop();
352 PlanExplainsStop (Event *event_ptr);
355 ShouldStop (Event *event_ptr) = 0;
358 ShouldAutoContinue (Event *event_ptr)
363 // Whether a "stop class" event should be reported to the "outside world". In general
364 // if a thread plan is active, events should not be reported.
367 ShouldReportStop (Event *event_ptr);
370 ShouldReportRun (Event *event_ptr);
373 SetStopOthers (bool new_value);
378 // This is the wrapper for DoWillResume that does generic ThreadPlan logic, then
379 // calls DoWillResume.
381 WillResume (lldb::StateType resume_state, bool current_plan);
389 return m_is_master_plan;
393 SetIsMasterPlan (bool value)
395 bool old_value = m_is_master_plan;
396 m_is_master_plan = value;
404 SetOkayToDiscard (bool value)
406 m_okay_to_discard = value;
409 // The base class MischiefManaged does some cleanup - so you have to call it
410 // in your MischiefManaged derived class.
417 // Any cleanup that a plan might want to do in case the thread goes away
418 // in the middle of the plan being queued on a thread can be done here.
424 return m_plan_private;
428 SetPrivate (bool input)
430 m_plan_private = input;
439 // This pushes a plan onto the plan stack of the current plan's thread.
441 PushPlan (lldb::ThreadPlanSP &thread_plan_sp)
443 m_thread.PushPlan (thread_plan_sp);
446 ThreadPlanKind GetKind() const
455 SetPlanComplete (bool success = true);
466 return m_plan_succeeded;
475 lldb::ThreadPlanTracerSP &
476 GetThreadPlanTracer()
482 SetThreadPlanTracer (lldb::ThreadPlanTracerSP new_tracer_sp)
484 m_tracer_sp = new_tracer_sp;
490 if (m_tracer_sp && m_tracer_sp->TracingEnabled())
494 // Some thread plans hide away the actual stop info which caused any particular stop. For
495 // instance the ThreadPlanCallFunction restores the original stop reason so that stopping and
496 // calling a few functions won't lose the history of the run.
497 // This call can be implemented to get you back to the real stop info.
498 virtual lldb::StopInfoSP
501 return m_thread.GetStopInfo ();
504 virtual lldb::ValueObjectSP
505 GetReturnValueObject ()
507 return lldb::ValueObjectSP();
510 // If a thread plan stores the state before it was run, then you might
511 // want to restore the state when it is done. This will do that job.
512 // This is mostly useful for artificial plans like CallFunction plans.
517 // Nothing to do in general.
528 //------------------------------------------------------------------
529 // Classes that inherit from ThreadPlan can see and modify these
530 //------------------------------------------------------------------
533 DoWillResume (lldb::StateType resume_state, bool current_plan) { return true; };
536 DoPlanExplainsStop (Event *event_ptr) = 0;
538 // This gets the previous plan to the current plan (for forwarding requests).
539 // This is mostly a formal requirement, it allows us to make the Thread's
540 // GetPreviousPlan protected, but only friend ThreadPlan to thread.
545 return m_thread.GetPreviousPlan (this);
548 // This forwards the private Thread::GetPrivateStopInfo which is generally what
549 // ThreadPlan's need to know.
554 return m_thread.GetPrivateStopInfo ();
558 SetStopInfo (lldb::StopInfoSP stop_reason_sp)
560 m_thread.SetStopInfo (stop_reason_sp);
564 CachePlanExplainsStop (bool does_explain)
566 m_cached_plan_explains_stop = does_explain ? eLazyBoolYes : eLazyBoolNo;
570 GetCachedPlanExplainsStop () const
572 return m_cached_plan_explains_stop;
575 virtual lldb::StateType
576 GetPlanRunState () = 0;
583 //------------------------------------------------------------------
584 // For ThreadPlan only
585 //------------------------------------------------------------------
586 static lldb::user_id_t GetNextID ();
588 ThreadPlanKind m_kind;
590 Mutex m_plan_complete_mutex;
591 LazyBool m_cached_plan_explains_stop;
592 bool m_plan_complete;
594 bool m_okay_to_discard;
595 bool m_is_master_plan;
596 bool m_plan_succeeded;
598 lldb::ThreadPlanTracerSP m_tracer_sp;
601 DISALLOW_COPY_AND_ASSIGN(ThreadPlan);
604 //----------------------------------------------------------------------
606 // Threads are assumed to always have at least one plan on the plan stack.
607 // This is put on the plan stack when a thread is destroyed so that if you
608 // accidentally access a thread after it is destroyed you won't crash.
609 // But asking questions of the ThreadPlanNull is definitely an error.
610 //----------------------------------------------------------------------
612 class ThreadPlanNull : public ThreadPlan
615 ThreadPlanNull (Thread &thread);
616 virtual ~ThreadPlanNull ();
619 GetDescription (Stream *s,
620 lldb::DescriptionLevel level);
623 ValidatePlan (Stream *error);
626 ShouldStop (Event *event_ptr);
648 DoPlanExplainsStop (Event *event_ptr);
650 virtual lldb::StateType
656 } // namespace lldb_private
658 #endif // liblldb_ThreadPlan_h_