Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
668 lines (576 sloc) 25 KB
//===-- ThreadPlan.h --------------------------------------------*- C++ -*-===//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#ifndef liblldb_ThreadPlan_h_
#define liblldb_ThreadPlan_h_
#include <mutex>
#include <string>
#include "lldb/Target/Process.h"
#include "lldb/Target/StopInfo.h"
#include "lldb/Target/Target.h"
#include "lldb/Target/Thread.h"
#include "lldb/Target/ThreadPlanTracer.h"
#include "lldb/Utility/UserID.h"
#include "lldb/lldb-private.h"
namespace lldb_private {
// ThreadPlan:
// This is the pure virtual base class for thread plans.
// The thread plans provide the "atoms" of behavior that
// all the logical process control, either directly from commands or through
// more complex composite plans will rely on.
// Plan Stack:
// The thread maintaining a thread plan stack, and you program the actions of a
// particular thread
// by pushing plans onto the plan stack.
// There is always a "Current" plan, which is the top of the plan stack,
// though in some cases
// a plan may defer to plans higher in the stack for some piece of information
// (let us define that the plan stack grows downwards).
// The plan stack is never empty, there is always a Base Plan which persists
// through the life
// of the running process.
// Creating Plans:
// The thread plan is generally created and added to the plan stack through the
// QueueThreadPlanFor... API
// in lldb::Thread. Those API's will return the plan that performs the named
// operation in a manner
// appropriate for the current process. The plans in lldb/source/Target are
// generic
// implementations, but a Process plugin can override them.
// ValidatePlan is then called. If it returns false, the plan is unshipped.
// This is a little
// convenience which keeps us from having to error out of the constructor.
// Then the plan is added to the plan stack. When the plan is added to the
// plan stack its DidPush
// will get called. This is useful if a plan wants to push any additional
// plans as it is constructed,
// since you need to make sure you're already on the stack before you push
// additional plans.
// Completed Plans:
// When the target process stops the plans are queried, among other things, for
// whether their job is done.
// If it is they are moved from the plan stack to the Completed Plan stack in
// reverse order from their position
// on the plan stack (since multiple plans may be done at a given stop.) This
// is used primarily so that
// the lldb::Thread::StopInfo for the thread can be set properly. If one plan
// pushes another to achieve part of
// its job, but it doesn't want that sub-plan to be the one that sets the
// StopInfo, then call SetPrivate on the
// sub-plan when you create it, and the Thread will pass over that plan in
// reporting the reason for the stop.
// Discarded plans:
// Your plan may also get discarded, i.e. moved from the plan stack to the
// "discarded plan stack". This can
// happen, for instance, if the plan is calling a function and the function
// call crashes and you want
// to unwind the attempt to call. So don't assume that your plan will always
// successfully stop. Which leads to:
// Cleaning up after your plans:
// When the plan is moved from the plan stack its WillPop method is always
// called, no matter why. Once it is
// moved off the plan stack it is done, and won't get a chance to run again.
// So you should
// undo anything that affects target state in this method. But be sure to
// leave the plan able to correctly
// fill the StopInfo, however.
// N.B. Don't wait to do clean up target state till the destructor, since that
// will usually get called when
// the target resumes, and you want to leave the target state correct for new
// plans in the time between when
// your plan gets unshipped and the next resume.
// Thread State Checkpoint:
// Note that calling functions on target process (ThreadPlanCallFunction) changes
// current thread state. The function can be called either by direct user demand or
// internally, for example lldb allocates memory on device to calculate breakpoint
// condition expression - on Linux it is performed by calling mmap on device.
// ThreadStateCheckpoint saves Thread state (stop info and completed
// plan stack) to restore it after completing function call.
// Over the lifetime of the plan, various methods of the ThreadPlan are then
// called in response to changes of state in
// the process we are debugging as follows:
// Resuming:
// When the target process is about to be restarted, the plan's WillResume
// method is called,
// giving the plan a chance to prepare for the run. If WillResume returns
// false, then the
// process is not restarted. Be sure to set an appropriate error value in the
// Process if
// you have to do this. Note, ThreadPlans actually implement DoWillResume,
// WillResume wraps that call.
// Next the "StopOthers" method of all the threads are polled, and if one
// thread's Current plan
// returns "true" then only that thread gets to run. If more than one returns
// "true" the threads that want to run solo
// get run one by one round robin fashion. Otherwise all are let to run.
// Note, the way StopOthers is implemented, the base class implementation just
// asks the previous plan. So if your plan
// has no opinion about whether it should run stopping others or not, just
// don't implement StopOthers, and the parent
// will be asked.
// Finally, for each thread that is running, it run state is set to the return
// of RunState from the
// thread's Current plan.
// Responding to a stop:
// When the target process stops, the plan is called in the following stages:
// First the thread asks the Current Plan if it can handle this stop by calling
// PlanExplainsStop.
// If the Current plan answers "true" then it is asked if the stop should
// percolate all the way to the
// user by calling the ShouldStop method. If the current plan doesn't explain
// the stop, then we query up
// the plan stack for a plan that does explain the stop. The plan that does
// explain the stop then needs to
// figure out what to do about the plans below it in the stack. If the stop is
// recoverable, then the plan that
// understands it can just do what it needs to set up to restart, and then
// continue.
// Otherwise, the plan that understood the stop should call DiscardPlanStack to
// clean up the stack below it.
// Note, plans actually implement DoPlanExplainsStop, the result is cached in
// PlanExplainsStop so the DoPlanExplainsStop
// itself will only get called once per stop.
// Master plans:
// In the normal case, when we decide to stop, we will collapse the plan stack
// up to the point of the plan that understood
// the stop reason. However, if a plan wishes to stay on the stack after an
// event it didn't directly handle
// it can designate itself a "Master" plan by responding true to IsMasterPlan,
// and then if it wants not to be
// discarded, it can return false to OkayToDiscard, and it and all its dependent
// plans will be preserved when
// we resume execution.
// The other effect of being a master plan is that when the Master plan is done
// , if it has set "OkayToDiscard" to false,
// then it will be popped & execution will stop and return to the user.
// Remember that if OkayToDiscard is false, the
// plan will be popped and control will be given to the next plan above it on
// the stack So setting OkayToDiscard to
// false means the user will regain control when the MasterPlan is completed.
// Between these two controls this allows things like: a MasterPlan/DontDiscard
// Step Over to hit a breakpoint, stop and
// return control to the user, but then when the user continues, the step out
// succeeds.
// Even more tricky, when the breakpoint is hit, the user can continue to step
// in/step over/etc, and finally when they
// continue, they will finish up the Step Over.
// FIXME: MasterPlan & OkayToDiscard aren't really orthogonal. MasterPlan
// designation means that this plan controls
// it's fate and the fate of plans below it. OkayToDiscard tells whether the
// MasterPlan wants to stay on the stack. I
// originally thought "MasterPlan-ness" would need to be a fixed characteristic
// of a ThreadPlan, in which case you needed
// the extra control. But that doesn't seem to be true. So we should be able
// to convert to only MasterPlan status to mean
// the current "MasterPlan/DontDiscard". Then no plans would be MasterPlans by
// default, and you would set the ones you
// wanted to be "user level" in this way.
// Actually Stopping:
// If a plan says responds "true" to ShouldStop, then it is asked if it's job
// is complete by calling
// MischiefManaged. If that returns true, the plan is popped from the plan
// stack and added to the
// Completed Plan Stack. Then the next plan in the stack is asked if it
// ShouldStop, and it returns "true",
// it is asked if it is done, and if yes popped, and so on till we reach a plan
// that is not done.
// Since you often know in the ShouldStop method whether your plan is complete,
// as a convenience you can call
// SetPlanComplete and the ThreadPlan implementation of MischiefManaged will
// return "true", without your having
// to redo the calculation when your sub-classes MischiefManaged is called. If
// you call SetPlanComplete, you can
// later use IsPlanComplete to determine whether the plan is complete. This is
// only a convenience for sub-classes,
// the logic in lldb::Thread will only call MischiefManaged.
// One slightly tricky point is you have to be careful using SetPlanComplete in
// PlanExplainsStop because you
// are not guaranteed that PlanExplainsStop for a plan will get called before
// ShouldStop gets called. If your sub-plan
// explained the stop and then popped itself, only your ShouldStop will get
// called.
// If ShouldStop for any thread returns "true", then the WillStop method of the
// Current plan of
// all threads will be called, the stop event is placed on the Process's public
// broadcaster, and
// control returns to the upper layers of the debugger.
// Reporting the stop:
// When the process stops, the thread is given a StopReason, in the form of a
// StopInfo object. If there is a completed
// plan corresponding to the stop, then the "actual" stop reason can be
// suppressed, and instead a StopInfoThreadPlan
// object will be cons'ed up from the top completed plan in the stack.
// However, if the plan doesn't want to be
// the stop reason, then it can call SetPlanComplete and pass in "false" for
// the "success" parameter. In that case,
// the real stop reason will be used instead. One exapmle of this is the
// "StepRangeStepIn" thread plan. If it stops
// because of a crash or breakpoint hit, it wants to unship itself, because it
// isn't so useful to have step in keep going
// 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.
// Cleaning up the plan stack:
// One of the complications of MasterPlans is that you may get past the limits
// of a plan without triggering it to clean
// itself up. For instance, if you are doing a MasterPlan StepOver, and hit a
// breakpoint in a called function, then
// step over enough times to step out of the initial StepOver range, each of
// the step overs will explain the stop &
// take themselves off the stack, but control would never be returned to the
// original StepOver. Eventually, the user
// will continue, and when that continue stops, the old stale StepOver plan
// that was left on the stack will get woken
// up and notice it is done. But that can leave junk on the stack for a while.
// To avoid that, the plans implement a
// "IsPlanStale" method, that can check whether it is relevant anymore. On
// stop, after the regular plan negotiation,
// the remaining plan stack is consulted and if any plan says it is stale, it
// and the plans below it are discarded from
// the stack.
// Automatically Resuming:
// If ShouldStop for all threads returns "false", then the target process will
// resume. This then cycles back to
// Resuming above.
// Reporting eStateStopped events when the target is restarted:
// If a plan decides to auto-continue the target by returning "false" from
// ShouldStop, then it will be asked
// whether the Stopped event should still be reported. For instance, if you
// hit a breakpoint that is a User set
// breakpoint, but the breakpoint callback said to continue the target process,
// you might still want to inform
// the upper layers of lldb that the stop had happened.
// The way this works is every thread gets to vote on whether to report the
// stop. If all votes are eVoteNoOpinion,
// then the thread list will decide what to do (at present it will pretty much
// always suppress these stopped events.)
// If there is an eVoteYes, then the event will be reported regardless of the
// other votes. If there is an eVoteNo
// and no eVoteYes's, then the event won't be reported.
// One other little detail here, sometimes a plan will push another plan onto
// the plan stack to do some part of
// the first plan's job, and it would be convenient to tell that plan how it
// should respond to ShouldReportStop.
// You can do that by setting the stop_vote in the child plan when you create
// it.
// Suppressing the initial eStateRunning event:
// The private process running thread will take care of ensuring that only one
// "eStateRunning" event will be
// delivered to the public Process broadcaster per public eStateStopped event.
// However there are some cases
// where the public state of this process is eStateStopped, but a thread plan
// needs to restart the target, but
// doesn't want the running event to be publicly broadcast. The obvious
// example of this is running functions
// by hand as part of expression evaluation. To suppress the running event
// return eVoteNo from ShouldReportStop,
// to force a running event to be reported return eVoteYes, in general though
// you should return eVoteNoOpinion
// which will allow the ThreadList to figure out the right thing to do.
// The run_vote argument to the constructor works like stop_vote, and is a way
// for a plan to instruct a sub-plan
// on how to respond to ShouldReportStop.
class ThreadPlan : public std::enable_shared_from_this<ThreadPlan>,
public UserID {
typedef enum { eAllThreads, eSomeThreads, eThisThread } ThreadScope;
// We use these enums so that we can cast a base thread plan to it's real
// type without having to resort to dynamic casting.
typedef enum {
} ThreadPlanKind;
// Constructors and Destructors
ThreadPlan(ThreadPlanKind kind, const char *name, Thread &thread,
Vote stop_vote, Vote run_vote);
virtual ~ThreadPlan();
/// Returns the name of this thread plan.
/// @return
/// A const char * pointer to the thread plan's name.
const char *GetName() const { return m_name.c_str(); }
/// Returns the Thread that is using this thread plan.
/// @return
/// A pointer to the thread plan's owning thread.
Thread &GetThread() { return m_thread; }
const Thread &GetThread() const { return m_thread; }
Target &GetTarget() { return m_thread.GetProcess()->GetTarget(); }
const Target &GetTarget() const { return m_thread.GetProcess()->GetTarget(); }
/// Print a description of this thread to the stream \a s.
/// \a thread.
/// @param[in] s
/// The stream to which to print the description.
/// @param[in] level
/// The level of description desired. Note that eDescriptionLevelBrief
/// will be used in the stop message printed when the plan is complete.
virtual void GetDescription(Stream *s, lldb::DescriptionLevel level) = 0;
/// Returns whether this plan could be successfully created.
/// @param[in] error
/// A stream to which to print some reason why the plan could not be
/// created.
/// Can be NULL.
/// @return
/// \b true if the plan should be queued, \b false otherwise.
virtual bool ValidatePlan(Stream *error) = 0;
bool TracerExplainsStop() {
if (!m_tracer_sp)
return false;
return m_tracer_sp->TracerExplainsStop();
lldb::StateType RunState();
bool PlanExplainsStop(Event *event_ptr);
virtual bool ShouldStop(Event *event_ptr) = 0;
virtual bool ShouldAutoContinue(Event *event_ptr) { return false; }
// Whether a "stop class" event should be reported to the "outside world".
// In general if a thread plan is active, events should not be reported.
virtual Vote ShouldReportStop(Event *event_ptr);
virtual Vote ShouldReportRun(Event *event_ptr);
virtual void SetStopOthers(bool new_value);
virtual bool StopOthers();
// This is the wrapper for DoWillResume that does generic ThreadPlan logic,
// then calls DoWillResume.
bool WillResume(lldb::StateType resume_state, bool current_plan);
virtual bool WillStop() = 0;
bool IsMasterPlan() { return m_is_master_plan; }
bool SetIsMasterPlan(bool value) {
bool old_value = m_is_master_plan;
m_is_master_plan = value;
return old_value;
virtual bool OkayToDiscard();
void SetOkayToDiscard(bool value) { m_okay_to_discard = value; }
// The base class MischiefManaged does some cleanup - so you have to call it
// in your MischiefManaged derived class.
virtual bool MischiefManaged();
virtual void ThreadDestroyed() {
// Any cleanup that a plan might want to do in case the thread goes away in
// the middle of the plan being queued on a thread can be done here.
bool GetPrivate() { return m_plan_private; }
void SetPrivate(bool input) { m_plan_private = input; }
virtual void DidPush();
virtual void WillPop();
// This pushes a plan onto the plan stack of the current plan's thread.
void PushPlan(lldb::ThreadPlanSP &thread_plan_sp) {
ThreadPlanKind GetKind() const { return m_kind; }
bool IsPlanComplete();
void SetPlanComplete(bool success = true);
virtual bool IsPlanStale() { return false; }
bool PlanSucceeded() { return m_plan_succeeded; }
virtual bool IsBasePlan() { return false; }
lldb::ThreadPlanTracerSP &GetThreadPlanTracer() { return m_tracer_sp; }
void SetThreadPlanTracer(lldb::ThreadPlanTracerSP new_tracer_sp) {
m_tracer_sp = new_tracer_sp;
void DoTraceLog() {
if (m_tracer_sp && m_tracer_sp->TracingEnabled())
// Some thread plans hide away the actual stop info which caused any
// particular stop. For instance the ThreadPlanCallFunction restores the
// original stop reason so that stopping and calling a few functions won't
// lose the history of the run. This call can be implemented to get you back
// to the real stop info.
virtual lldb::StopInfoSP GetRealStopInfo() { return m_thread.GetStopInfo(); }
// If the completion of the thread plan stepped out of a function, the return
// value of the function might have been captured by the thread plan
// (currently only ThreadPlanStepOut does this.) If so, the ReturnValueObject
// can be retrieved from here.
virtual lldb::ValueObjectSP GetReturnValueObject() {
return lldb::ValueObjectSP();
// If the thread plan managing the evaluation of a user expression lives
// longer than the command that instigated the expression (generally because
// the expression evaluation hit a breakpoint, and the user regained control
// at that point) a subsequent process control command step/continue/etc.
// might complete the expression evaluations. If so, the result of the
// expression evaluation will show up here.
virtual lldb::ExpressionVariableSP GetExpressionVariable() {
return lldb::ExpressionVariableSP();
// If a thread plan stores the state before it was run, then you might want
// to restore the state when it is done. This will do that job. This is
// mostly useful for artificial plans like CallFunction plans.
virtual bool RestoreThreadState() {
// Nothing to do in general.
return true;
virtual bool IsVirtualStep() { return false; }
virtual bool SetIterationCount(size_t count) {
if (m_takes_iteration_count) {
// Don't tell me to do something 0 times...
if (count == 0)
return false;
m_iteration_count = count;
return m_takes_iteration_count;
virtual size_t GetIterationCount() {
if (!m_takes_iteration_count)
return 0;
return m_iteration_count;
// Classes that inherit from ThreadPlan can see and modify these
virtual bool DoWillResume(lldb::StateType resume_state, bool current_plan) {
return true;
virtual bool DoPlanExplainsStop(Event *event_ptr) = 0;
// This gets the previous plan to the current plan (for forwarding requests).
// This is mostly a formal requirement, it allows us to make the Thread's
// GetPreviousPlan protected, but only friend ThreadPlan to thread.
ThreadPlan *GetPreviousPlan() { return m_thread.GetPreviousPlan(this); }
// This forwards the private Thread::GetPrivateStopInfo which is generally
// what ThreadPlan's need to know.
lldb::StopInfoSP GetPrivateStopInfo() {
return m_thread.GetPrivateStopInfo();
void SetStopInfo(lldb::StopInfoSP stop_reason_sp) {
void CachePlanExplainsStop(bool does_explain) {
m_cached_plan_explains_stop = does_explain ? eLazyBoolYes : eLazyBoolNo;
LazyBool GetCachedPlanExplainsStop() const {
return m_cached_plan_explains_stop;
virtual lldb::StateType GetPlanRunState() = 0;
bool IsUsuallyUnexplainedStopReason(lldb::StopReason);
Status m_status;
Thread &m_thread;
Vote m_stop_vote;
Vote m_run_vote;
bool m_takes_iteration_count;
bool m_could_not_resolve_hw_bp;
int32_t m_iteration_count = 1;
// For ThreadPlan only
static lldb::user_id_t GetNextID();
ThreadPlanKind m_kind;
std::string m_name;
std::recursive_mutex m_plan_complete_mutex;
LazyBool m_cached_plan_explains_stop;
bool m_plan_complete;
bool m_plan_private;
bool m_okay_to_discard;
bool m_is_master_plan;
bool m_plan_succeeded;
lldb::ThreadPlanTracerSP m_tracer_sp;
// ThreadPlanNull:
// Threads are assumed to always have at least one plan on the plan stack. This
// is put on the plan stack when a thread is destroyed so that if you
// accidentally access a thread after it is destroyed you won't crash. But
// asking questions of the ThreadPlanNull is definitely an error.
class ThreadPlanNull : public ThreadPlan {
ThreadPlanNull(Thread &thread);
~ThreadPlanNull() override;
void GetDescription(Stream *s, lldb::DescriptionLevel level) override;
bool ValidatePlan(Stream *error) override;
bool ShouldStop(Event *event_ptr) override;
bool MischiefManaged() override;
bool WillStop() override;
bool IsBasePlan() override { return true; }
bool OkayToDiscard() override { return false; }
const Status &GetStatus() { return m_status; }
bool DoPlanExplainsStop(Event *event_ptr) override;
lldb::StateType GetPlanRunState() override;
} // namespace lldb_private
#endif // liblldb_ThreadPlan_h_