ThreadPlan.h | Explore in Territory

//===-- ThreadPlan.h --------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_TARGET_THREADPLAN_H
#define LLDB_TARGET_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 DidPop 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.
//
//  Controlling 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 "Controlling" plan by responding
//  true to IsControllingPlan, 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 controlling plan is that when the Controlling
//  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 ControllingPlan is completed.
//
//  Between these two controls this allows things like: a
//  ControllingPlan/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: ControllingPlan & OkayToDiscard aren't really orthogonal.
//  ControllingPlan
//  designation means that this plan controls it's fate and the fate of plans
//  below it.  OkayToDiscard tells whether the ControllingPlan wants to stay on
//  the stack.  I originally thought "ControllingPlan-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
//  ControllingPlan status to mean the current "ControllingPlan/DontDiscard".
//  Then no plans would be ControllingPlans 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
//  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 ControllingPlans 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 ControllingPlan 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 report_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
//  report_run_vote argument to the constructor works like report_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 { … };

// 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 { … };

} // namespace lldb_private

#endif // LLDB_TARGET_THREADPLAN_H
llvm/lldb/include/lldb/Target/ThreadPlan.h
