[Lldb-commits] [lldb] 34d56b0 - [ThreadPlan] Reflow docs to fit the 80 column limit, NFC
Vedant Kumar via lldb-commits
lldb-commits at lists.llvm.org
Tue Nov 10 16:16:03 PST 2020
Author: Vedant Kumar
Date: 2020-11-10T16:14:52-08:00
New Revision: 34d56b05fd78f0d3043f7f02badf7067cecadb30
URL: https://github.com/llvm/llvm-project/commit/34d56b05fd78f0d3043f7f02badf7067cecadb30
DIFF: https://github.com/llvm/llvm-project/commit/34d56b05fd78f0d3043f7f02badf7067cecadb30.diff
LOG: [ThreadPlan] Reflow docs to fit the 80 column limit, NFC
Added:
Modified:
lldb/include/lldb/Target/ThreadPlan.h
Removed:
################################################################################
diff --git a/lldb/include/lldb/Target/ThreadPlan.h b/lldb/include/lldb/Target/ThreadPlan.h
index 8c2f9776eeb3..f4cd2b18f01a 100644
--- a/lldb/include/lldb/Target/ThreadPlan.h
+++ b/lldb/include/lldb/Target/ThreadPlan.h
@@ -23,310 +23,260 @@
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.
+// 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
+// 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.
+// 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
+// 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.
+// 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.
+// 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.
+// 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:
+// "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
+// 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.
+// 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.
+// 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:
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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.
+// 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
+// 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,
+// 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
+// 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.
+// 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 example 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.
+// 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
+// example 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.
+// 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.
+// 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.
+// 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.
+// 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.
-//
+// "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 {
More information about the lldb-commits
mailing list