From 34d56b05fd78f0d3043f7f02badf7067cecadb30 Mon Sep 17 00:00:00 2001 From: Vedant Kumar Date: Tue, 10 Nov 2020 15:24:07 -0800 Subject: [PATCH] [ThreadPlan] Reflow docs to fit the 80 column limit, NFC --- lldb/include/lldb/Target/ThreadPlan.h | 378 +++++++++++++++------------------- 1 file changed, 164 insertions(+), 214 deletions(-) diff --git a/lldb/include/lldb/Target/ThreadPlan.h b/lldb/include/lldb/Target/ThreadPlan.h index 8c2f977..f4cd2b1 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, public UserID { -- 2.7.4