[ThreadPlan] Reflow docs to fit the 80 column limit, NFC

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
+//  The thread plans provide the "atoms" of behavior that all the logical
-//  all the logical process control, either directly from commands or through
+//  process control, either directly from commands or through more complex
-//  more complex composite plans will rely on.
+//  composite plans will rely on.
 //
 //  Plan Stack:
 //
-//  The thread maintaining a thread plan stack, and you program the actions of a
+//  The thread maintaining a thread plan stack, and you program the actions of
-//  particular thread
+//  a particular thread by pushing plans onto the plan stack.  There is always
-//  by pushing plans onto the plan stack.
+//  a "Current" plan, which is the top of the plan stack, though in some cases
-//  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
+//  through the life of the running process.
-//  of the running process.
 //
 //
 //  Creating Plans:
 //
-//  The thread plan is generally created and added to the plan stack through the
+//  The thread plan is generally created and added to the plan stack through
-//  QueueThreadPlanFor... API
+//  the QueueThreadPlanFor... API in lldb::Thread.  Those API's will return the
-//  in lldb::Thread.  Those API's will return the plan that performs the named
+//  plan that performs the named operation in a manner appropriate for the
-//  operation in a manner
+//  current process.  The plans in lldb/source/Target are generic
-//  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
+//  This is a little convenience which keeps us from having to error out of the
-//  convenience which keeps us from having to error out of the constructor.
+//  constructor.
 //
 //  Then the plan is added to the plan stack.  When the plan is added to the
-//  plan stack its DidPush
+//  plan stack its DidPush will get called.  This is useful if a plan wants to
-//  will get called.  This is useful if a plan wants to push any additional
+//  push any additional plans as it is constructed, since you need to make sure
-//  plans as it is constructed,
+//  you're already on the stack before you push additional plans.
-//  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
+//  When the target process stops the plans are queried, among other things,
-//  whether their job is done.
+//  for whether their job is done.  If it is they are moved from the plan stack
-//  If it is they are moved from the plan stack to the Completed Plan stack in
+//  to the Completed Plan stack in reverse order from their position on the
-//  reverse order from their position
+//  plan stack (since multiple plans may be done at a given stop.)  This is
-//  on the plan stack (since multiple plans may be done at a given stop.)  This
+//  used primarily so that the lldb::Thread::StopInfo for the thread can be set
-//  is used primarily so that
+//  properly.  If one plan pushes another to achieve part of its job, but it
-//  the lldb::Thread::StopInfo for the thread can be set properly.  If one plan
+//  doesn't want that sub-plan to be the one that sets the StopInfo, then call
-//  pushes another to achieve part of
+//  SetPrivate on the sub-plan when you create it, and the Thread will pass
-//  its job, but it doesn't want that sub-plan to be the one that sets the
+//  over that plan in reporting the reason for the stop.
-//  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
+//  "discarded plan stack".  This can happen, for instance, if the plan is
-//  happen, for instance, if the plan is calling a function and the function
+//  calling a function and the function call crashes and you want to unwind the
-//  call crashes and you want
+//  attempt to call.  So don't assume that your plan will always successfully
-//  to unwind the attempt to call.  So don't assume that your plan will always
+//  stop.  Which leads to:
-//  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
+//  called, no matter why.  Once it is moved off the plan stack it is done, and
-//  moved off the plan stack it is done, and won't get a chance to run again.
+//  won't get a chance to run again.  So you should undo anything that affects
-//  So you should
+//  target state in this method.  But be sure to leave the plan able to
-//  undo anything that affects target state in this method.  But be sure to
+//  correctly fill the StopInfo, however.  N.B. Don't wait to do clean up
-//  leave the plan able to correctly
+//  target state till the destructor, since that will usually get called when
-//  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
+//  plans in the time between when your plan gets unshipped and the next
-//  your plan gets unshipped and the next resume.
+//  resume.
 //
 //  Thread State Checkpoint:
 //
-//  Note that calling functions on target process (ThreadPlanCallFunction) changes
+//  Note that calling functions on target process (ThreadPlanCallFunction)
-//  current thread state. The function can be called either by direct user demand or
+//  changes current thread state. The function can be called either by direct
-//  internally, for example lldb allocates memory on device to calculate breakpoint
+//  user demand or internally, for example lldb allocates memory on device to
-//  condition expression - on Linux it is performed by calling mmap on device.
+//  calculate breakpoint condition expression - on Linux it is performed by
-//  ThreadStateCheckpoint saves Thread state (stop info and completed
+//  calling mmap on device.  ThreadStateCheckpoint saves Thread state (stop
-//  plan stack) to restore it after completing function call.
+//  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
+//  called in response to changes of state in the process we are debugging as
-//  the process we are debugging as follows:
+//  follows:
 //
 //  Resuming:
 //
 //  When the target process is about to be restarted, the plan's WillResume
-//  method is called,
+//  method is called, giving the plan a chance to prepare for the run.  If
-//  giving the plan a chance to prepare for the run.  If WillResume returns
+//  WillResume returns false, then the process is not restarted.  Be sure to
-//  false, then the
+//  set an appropriate error value in the Process if you have to do this.
-//  process is not restarted.  Be sure to set an appropriate error value in the
+//  Note, ThreadPlans actually implement DoWillResume, WillResume wraps that
-//  Process if
+//  call.
-//  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
+//  thread's Current plan returns "true" then only that thread gets to run.  If
-//  returns "true" then only that thread gets to run.  If more than one returns
+//  more than one returns "true" the threads that want to run solo get run one
-//  "true" the threads that want to run solo
+//  by one round robin fashion.  Otherwise all are let to run.
-//  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
+//  asks the previous plan.  So if your plan has no opinion about whether it
-//  has no opinion about whether it should run stopping others or not, just
+//  should run stopping others or not, just don't implement StopOthers, and the
-//  don't implement StopOthers, and the parent
+//  parent will be asked.
-//  will be asked.
 //
 //  Finally, for each thread that is running, it run state is set to the return
-//  of RunState from the
+//  of RunState from the thread's Current plan.
-//  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
+//  First the thread asks the Current Plan if it can handle this stop by
-//  PlanExplainsStop.
+//  calling PlanExplainsStop.  If the Current plan answers "true" then it is
-//  If the Current plan answers "true" then it is asked if the stop should
+//  asked if the stop should percolate all the way to the user by calling the
-//  percolate all the way to the
+//  ShouldStop method.  If the current plan doesn't explain the stop, then we
-//  user by calling the ShouldStop method.  If the current plan doesn't explain
+//  query up the plan stack for a plan that does explain the stop.  The plan
-//  the stop, then we query up
+//  that does explain the stop then needs to figure out what to do about the
-//  the plan stack for a plan that does explain the stop.  The plan that does
+//  plans below it in the stack.  If the stop is recoverable, then the plan
-//  explain the stop then needs to
+//  that understands it can just do what it needs to set up to restart, and
-//  figure out what to do about the plans below it in the stack.  If the stop is
+//  then continue.  Otherwise, the plan that understood the stop should call
-//  recoverable, then the plan that
+//  DiscardPlanStack to clean up the stack below it.  Note, plans actually
-//  understands it can just do what it needs to set up to restart, and then
+//  implement DoPlanExplainsStop, the result is cached in PlanExplainsStop so
-//  continue.
+//  the DoPlanExplainsStop itself will only get called once per stop.
-//  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
+//  In the normal case, when we decide to stop, we will  collapse the plan
-//  up to the point of the plan that understood
+//  stack up to the point of the plan that understood the stop reason.
-//  the stop reason.  However, if a plan wishes to stay on the stack after an
+//  However, if a plan wishes to stay on the stack after an event it didn't
-//  event it didn't directly handle
+//  directly handle it can designate itself a "Master" plan by responding true
-//  it can designate itself a "Master" plan by responding true to IsMasterPlan,
+//  to IsMasterPlan, and then if it wants not to be discarded, it can return
-//  and then if it wants not to be
+//  false to OkayToDiscard, and it and all its dependent plans will be
-//  discarded, it can return false to OkayToDiscard, and it and all its dependent
+//  preserved when we resume execution.
-//  plans will be preserved when
-//  we resume execution.
 //
-//  The other effect of being a master plan is that when the Master plan is done
+//  The other effect of being a master plan is that when the Master plan is
-//  , if it has set "OkayToDiscard" to false,
+//  done , if it has set "OkayToDiscard" to false, then it will be popped &
-//  then it will be popped & execution will stop and return to the user.
+//  execution will stop and return to the user.  Remember that if OkayToDiscard
-//  Remember that if OkayToDiscard is false, the
+//  is false, the plan will be popped and control will be given to the next
-//  plan will be popped and control will be given to the next plan above it on
+//  plan above it on the stack  So setting OkayToDiscard to false means the
-//  the stack  So setting OkayToDiscard to
+//  user will regain control when the MasterPlan is completed.
-//  false means the user will regain control when the MasterPlan is completed.
 //
-//  Between these two controls this allows things like: a MasterPlan/DontDiscard
+//  Between these two controls this allows things like: a
-//  Step Over to hit a breakpoint, stop and
+//  MasterPlan/DontDiscard Step Over to hit a breakpoint, stop and return
-//  return control to the user, but then when the user continues, the step out
+//  control to the user, but then when the user continues, the step out
-//  succeeds.
+//  succeeds.  Even more tricky, when the breakpoint is hit, the user can
-//  Even more tricky, when the breakpoint is hit, the user can continue to step
+//  continue to step in/step over/etc, and finally when they continue, they
-//  in/step over/etc, and finally when they
+//  will finish up the Step Over.
-//  continue, they will finish up the Step Over.
 //
 //  FIXME: MasterPlan & OkayToDiscard aren't really orthogonal.  MasterPlan
-//  designation means that this plan controls
+//  designation means that this plan controls it's fate and the fate of plans
-//  it's fate and the fate of plans below it.  OkayToDiscard tells whether the
+//  below it.  OkayToDiscard tells whether the MasterPlan wants to stay on the
-//  MasterPlan wants to stay on the stack.  I
+//  stack.  I originally thought "MasterPlan-ness" would need to be a fixed
-//  originally thought "MasterPlan-ness" would need to be a fixed characteristic
+//  characteristic of a ThreadPlan, in which case you needed the extra control.
-//  of a ThreadPlan, in which case you needed
+//  But that doesn't seem to be true.  So we should be able to convert to only
-//  the extra control.  But that doesn't seem to be true.  So we should be able
+//  MasterPlan status to mean the current "MasterPlan/DontDiscard".  Then no
-//  to convert to only MasterPlan status to mean
+//  plans would be MasterPlans by default, and you would set the ones you
-//  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
+//  is complete by calling MischiefManaged.  If that returns true, the plan is
-//  MischiefManaged.  If that returns true, the plan is popped from the plan
+//  popped from the plan stack and added to the Completed Plan Stack.  Then the
-//  stack and added to the
+//  next plan in the stack is asked if it ShouldStop, and  it returns "true",
-//  Completed Plan Stack.  Then the next plan in the stack is asked if it
+//  it is asked if it is done, and if yes popped, and so on till we reach a
-//  ShouldStop, and  it returns "true",
+//  plan that is not done.
-//  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,
+//  Since you often know in the ShouldStop method whether your plan is
-//  as a convenience you can call
+//  complete, as a convenience you can call SetPlanComplete and the ThreadPlan
-//  SetPlanComplete and the ThreadPlan implementation of MischiefManaged will
+//  implementation of MischiefManaged will return "true", without your having
-//  return "true", without your having
+//  to redo the calculation when your sub-classes MischiefManaged is called.
-//  to redo the calculation when your sub-classes MischiefManaged is called.  If
+//  If you call SetPlanComplete, you can later use IsPlanComplete to determine
-//  you call SetPlanComplete, you can
+//  whether the plan is complete.  This is only a convenience for sub-classes,
-//  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
+//  One slightly tricky point is you have to be careful using SetPlanComplete
-//  PlanExplainsStop because you
+//  in PlanExplainsStop because you are not guaranteed that PlanExplainsStop
-//  are not guaranteed that PlanExplainsStop for a plan will get called before
+//  for a plan will get called before ShouldStop gets called.  If your sub-plan
-//  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
+//  If ShouldStop for any thread returns "true", then the WillStop method of
-//  Current plan of
+//  the Current plan of all threads will be called, the stop event is placed on
-//  all threads will be called, the stop event is placed on the Process's public
+//  the Process's public broadcaster, and control returns to the upper layers
-//  broadcaster, and
+//  of the debugger.
-//  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
+//  StopInfo object.  If there is a completed plan corresponding to the stop,
-//  plan corresponding to the stop, then the "actual" stop reason can be
+//  then the "actual" stop reason can be suppressed, and instead a
-//  suppressed, and instead a StopInfoThreadPlan
+//  StopInfoThreadPlan object will be cons'ed up from the top completed plan in
-//  object will be cons'ed up from the top completed plan in the stack.
+//  the stack.  However, if the plan doesn't want to be the stop reason, then
-//  However, if the plan doesn't want to be
+//  it can call SetPlanComplete and pass in "false" for the "success"
-//  the stop reason, then it can call SetPlanComplete and pass in "false" for
+//  parameter.  In that case, the real stop reason will be used instead.  One
-//  the "success" parameter.  In that case,
+//  example of this is the "StepRangeStepIn" thread plan.  If it stops because
-//  the real stop reason will be used instead.  One example of this is the
+//  of a crash or breakpoint hit, it wants to unship itself, because it isn't
-//  "StepRangeStepIn" thread plan.  If it stops
+//  so useful to have step in keep going after a breakpoint hit.  But it can't
-//  because of a crash or breakpoint hit, it wants to unship itself, because it
+//  be the reason for the stop or no-one would see that they had hit a
-//  isn't so useful to have step in keep going
+//  breakpoint.
-//  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
+//  of a plan without triggering it to clean itself up.  For instance, if you
-//  itself up.  For instance, if you are doing a MasterPlan StepOver, and hit a
+//  are doing a MasterPlan StepOver, and hit a breakpoint in a called function,
-//  breakpoint in a called function, then
+//  then step over enough times to step out of the initial StepOver range, each
-//  step over enough times to step out of the initial StepOver range, each of
+//  of the step overs will explain the stop & take themselves off the stack,
-//  the step overs will explain the stop &
+//  but control would never be returned to the original StepOver.  Eventually,
-//  take themselves off the stack, but control would never be returned to the
+//  the user will continue, and when that continue stops, the old stale
-//  original StepOver.  Eventually, the user
+//  StepOver plan that was left on the stack will get woken up and notice it is
-//  will continue, and when that continue stops, the old stale StepOver plan
+//  done. But that can leave junk on the stack for a while.  To avoid that, the
-//  that was left on the stack will get woken
+//  plans implement a "IsPlanStale" method, that can check whether it is
-//  up and notice it is done. But that can leave junk on the stack for a while.
+//  relevant anymore.  On stop, after the regular plan negotiation, the
-//  To avoid that, the plans implement a
+//  remaining plan stack is consulted and if any plan says it is stale, it and
-//  "IsPlanStale" method, that can check whether it is relevant anymore.  On
+//  the plans below it are discarded from the stack.
-//  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
+//  resume.  This then cycles back to Resuming above.
-//  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
+//  ShouldStop, then it will be asked whether the Stopped event should still be
-//  whether the Stopped event should still be reported.  For instance, if you
+//  reported.  For instance, if you hit a breakpoint that is a User set
-//  hit a breakpoint that is a User set
+//  breakpoint, but the breakpoint callback said to continue the target
-//  breakpoint, but the breakpoint callback said to continue the target process,
+//  process, you might still want to inform the upper layers of lldb that the
-//  you might still want to inform
+//  stop had happened.  The way this works is every thread gets to vote on
-//  the upper layers of lldb that the stop had happened.
+//  whether to report the stop.  If all votes are eVoteNoOpinion, then the
-//  The way this works is every thread gets to vote on whether to report the
+//  thread list will decide what to do (at present it will pretty much always
-//  stop.  If all votes are eVoteNoOpinion,
+//  suppress these stopped events.) If there is an eVoteYes, then the event
-//  then the thread list will decide what to do (at present it will pretty much
+//  will be reported regardless of the other votes.  If there is an eVoteNo and
-//  always suppress these stopped events.)
+//  no eVoteYes's, then the event won't be reported.
-//  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 plan stack to do some part of the first plan's job, and it would be
-//  the first plan's job, and it would be convenient to tell that plan how it
+//  convenient to tell that plan how it should respond to ShouldReportStop.
-//  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
+//  "eStateRunning" event will be delivered to the public Process broadcaster
-//  delivered to the public Process broadcaster per public eStateStopped event.
+//  per public eStateStopped event.  However there are some cases where the
-//  However there are some cases
+//  public state of this process is eStateStopped, but a thread plan needs to
-//  where the public state of this process is eStateStopped, but a thread plan
+//  restart the target, but doesn't want the running event to be publicly
-//  needs to restart the target, but
+//  broadcast.  The obvious example of this is running functions by hand as
-//  doesn't want the running event to be publicly broadcast.  The obvious
+//  part of expression evaluation.  To suppress the running event return
-//  example of this is running functions
+//  eVoteNo from ShouldReportStop, to force a running event to be reported
-//  by hand as part of expression evaluation.  To suppress the running event
+//  return eVoteYes, in general though you should return eVoteNoOpinion which
-//  return eVoteNo from ShouldReportStop,
+//  will allow the ThreadList to figure out the right thing to do.  The
-//  to force a running event to be reported return eVoteYes, in general though
+//  run_vote argument to the constructor works like stop_vote, and is a way for
-//  you should return eVoteNoOpinion
+//  a plan to instruct a sub-plan on how to respond to ShouldReportStop.
-//  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 {