[lldb][NFC] Inclusive Language: rename master plan to controlling plan

[NFC] As part of using inclusive language within the llvm project, this patch
renames master plan to controlling plan in lldb.

Reviewed By: jingham

Differential Revision: https://reviews.llvm.org/D113019

lldb/docs/use/python-reference.rst

@@ -442,7 +442,7 @@ And for a MUCH fuller discussion of the whole state machine, see:
 https://github.com/llvm/llvm-project/blob/main/lldb/include/lldb/Target/ThreadPlan.h
 
 If you are reading those comments it is useful to know that scripted thread
-plans are set to be "MasterPlans", and not "OkayToDiscard".
+plans are set to be "ControllingPlans", and not "OkayToDiscard".
 
 To implement a scripted step, you define a python class that has the following
 methods:

lldb/include/lldb/Target/Thread.h

@@ -1015,7 +1015,8 @@ public:
 
   /// Discards the plans queued on the plan stack of the current thread.  This
   /// is
-  /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
+  /// arbitrated by the "Controlling" ThreadPlans, using the "OkayToDiscard"
+  /// call.
   //  But if \a force is true, all thread plans are discarded.
   void DiscardThreadPlans(bool force);
 

lldb/include/lldb/Target/ThreadPlan.h

@@ -144,39 +144,42 @@ namespace lldb_private {
 //  implement DoPlanExplainsStop, the result is cached in PlanExplainsStop so
 //  the DoPlanExplainsStop itself will only get called once per stop.
 //
-//  Master plans:
+//  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 "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
+//  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 master plan is that when the Master plan is
+//  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 MasterPlan is completed.
+//  user will regain control when the ControllingPlan is completed.
 //
 //  Between these two controls this allows things like: a
-//  MasterPlan/DontDiscard Step Over to hit a breakpoint, stop and return
+//  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: MasterPlan & OkayToDiscard aren't really orthogonal.  MasterPlan
+//  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 MasterPlan wants to stay on the
-//  stack.  I originally thought "MasterPlan-ness" would need to be a fixed
+//  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
-//  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.
+//  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:
@@ -224,9 +227,11 @@ namespace lldb_private {
 //
 //  Cleaning up the plan stack:
 //
-//  One of the complications of MasterPlans is that you may get past the limits
+//  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 MasterPlan StepOver, and hit a breakpoint in a called function,
+//  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,
@@ -386,11 +391,11 @@ public:
 
   virtual bool WillStop() = 0;
 
-  bool IsMasterPlan() { return m_is_master_plan; }
+  bool IsControllingPlan() { return m_is_controlling_plan; }
 
-  bool SetIsMasterPlan(bool value) {
-    bool old_value = m_is_master_plan;
-    m_is_master_plan = value;
+  bool SetIsControllingPlan(bool value) {
+    bool old_value = m_is_controlling_plan;
+    m_is_controlling_plan = value;
     return old_value;
   }
 
@@ -490,12 +495,12 @@ protected:
   virtual bool DoPlanExplainsStop(Event *event_ptr) = 0;
 
   // This pushes a plan onto the plan stack of the current plan's thread.
-  // Also sets the plans to private and not master plans.  A plan pushed by
+  // Also sets the plans to private and not controlling plans.  A plan pushed by
   // another thread plan is never either of the above.
   void PushPlan(lldb::ThreadPlanSP &thread_plan_sp) {
     GetThread().PushPlan(thread_plan_sp);
     thread_plan_sp->SetPrivate(true);
-    thread_plan_sp->SetIsMasterPlan(false);
+    thread_plan_sp->SetIsControllingPlan(false);
   }
 
   // This gets the previous plan to the current plan (for forwarding requests).
@@ -546,7 +551,7 @@ private:
   bool m_plan_complete;
   bool m_plan_private;
   bool m_okay_to_discard;
-  bool m_is_master_plan;
+  bool m_is_controlling_plan;
   bool m_plan_succeeded;
 
   lldb::ThreadPlanTracerSP m_tracer_sp;

lldb/include/lldb/Target/ThreadPlanStack.h

@@ -60,7 +60,7 @@ public:
 
   void DiscardAllPlans();
 
-  void DiscardConsultingMasterPlans();
+  void DiscardConsultingControllingPlans();
 
   lldb::ThreadPlanSP GetCurrentPlan() const;
 

lldb/source/API/SBThread.cpp

@@ -513,10 +513,10 @@ SBError SBThread::ResumeNewPlan(ExecutionContext &exe_ctx,
     return sb_error;
   }
 
-  // User level plans should be Master Plans so they can be interrupted, other
-  // plans executed, and then a "continue" will resume the plan.
+  // User level plans should be Controlling Plans so they can be interrupted,
+  // other plans executed, and then a "continue" will resume the plan.
   if (new_plan != nullptr) {
-    new_plan->SetIsMasterPlan(true);
+    new_plan->SetIsControllingPlan(true);
     new_plan->SetOkayToDiscard(false);
   }
 

lldb/source/Commands/CommandObjectThread.cpp

@@ -526,12 +526,12 @@ protected:
       return false;
     }
 
-    // If we got a new plan, then set it to be a master plan (User level Plans
-    // should be master plans so that they can be interruptible).  Then resume
-    // the process.
+    // If we got a new plan, then set it to be a controlling plan (User level
+    // Plans should be controlling plans so that they can be interruptible).
+    // Then resume the process.
 
     if (new_plan_sp) {
-      new_plan_sp->SetIsMasterPlan(true);
+      new_plan_sp->SetIsControllingPlan(true);
       new_plan_sp->SetOkayToDiscard(false);
 
       if (m_options.m_step_count > 1) {
@@ -1021,11 +1021,12 @@ protected:
             abort_other_plans, &address_list.front(), address_list.size(),
             m_options.m_stop_others, m_options.m_frame_idx, new_plan_status);
         if (new_plan_sp) {
-          // User level plans should be master plans so they can be interrupted
+          // User level plans should be controlling plans so they can be
+          // interrupted
           // (e.g. by hitting a breakpoint) and other plans executed by the
           // user (stepping around the breakpoint) and then a "continue" will
           // resume the original plan.
-          new_plan_sp->SetIsMasterPlan(true);
+          new_plan_sp->SetIsControllingPlan(true);
           new_plan_sp->SetOkayToDiscard(false);
         } else {
           result.SetError(new_plan_status);

lldb/source/Expression/FunctionCaller.cpp

@@ -254,7 +254,7 @@ lldb::ThreadPlanSP FunctionCaller::GetThreadPlanToCallFunction(
 
   lldb::ThreadPlanSP new_plan_sp(new ThreadPlanCallFunction(
       *thread, wrapper_address, CompilerType(), args, options));
-  new_plan_sp->SetIsMasterPlan(true);
+  new_plan_sp->SetIsControllingPlan(true);
   new_plan_sp->SetOkayToDiscard(false);
   return new_plan_sp;
 }

lldb/source/Target/Process.cpp

@@ -4526,7 +4526,8 @@ void Process::SettingsInitialize() { Thread::SettingsInitialize(); }
 void Process::SettingsTerminate() { Thread::SettingsTerminate(); }
 
 namespace {
-// RestorePlanState is used to record the "is private", "is master" and "okay
+// RestorePlanState is used to record the "is private", "is controlling" and
+// "okay
 // to discard" fields of the plan we are running, and reset it on Clean or on
 // destruction. It will only reset the state once, so you can call Clean and
 // then monkey with the state and it won't get reset on you again.
@@ -4537,7 +4538,7 @@ public:
       : m_thread_plan_sp(thread_plan_sp), m_already_reset(false) {
     if (m_thread_plan_sp) {
       m_private = m_thread_plan_sp->GetPrivate();
-      m_is_master = m_thread_plan_sp->IsMasterPlan();
+      m_is_controlling = m_thread_plan_sp->IsControllingPlan();
       m_okay_to_discard = m_thread_plan_sp->OkayToDiscard();
     }
   }
@@ -4548,7 +4549,7 @@ public:
     if (!m_already_reset && m_thread_plan_sp) {
       m_already_reset = true;
       m_thread_plan_sp->SetPrivate(m_private);
-      m_thread_plan_sp->SetIsMasterPlan(m_is_master);
+      m_thread_plan_sp->SetIsControllingPlan(m_is_controlling);
       m_thread_plan_sp->SetOkayToDiscard(m_okay_to_discard);
     }
   }
@@ -4557,7 +4558,7 @@ private:
   lldb::ThreadPlanSP m_thread_plan_sp;
   bool m_already_reset;
   bool m_private;
-  bool m_is_master;
+  bool m_is_controlling;
   bool m_okay_to_discard;
 };
 } // anonymous namespace
@@ -4708,11 +4709,11 @@ Process::RunThreadPlan(ExecutionContext &exe_ctx,
 
   thread_plan_sp->SetPrivate(false);
 
-  // The plans run with RunThreadPlan also need to be terminal master plans or
-  // when they are done we will end up asking the plan above us whether we
+  // The plans run with RunThreadPlan also need to be terminal controlling plans
+  // or when they are done we will end up asking the plan above us whether we
   // should stop, which may give the wrong answer.
 
-  thread_plan_sp->SetIsMasterPlan(true);
+  thread_plan_sp->SetIsControllingPlan(true);
   thread_plan_sp->SetOkayToDiscard(false);
 
   // If we are running some utility expression for LLDB, we now have to mark

lldb/source/Target/StopInfo.cpp

@@ -764,7 +764,7 @@ protected:
                         true,  // stop_other_threads
                         new_plan_status));
                 if (new_plan_sp && new_plan_status.Success()) {
-                  new_plan_sp->SetIsMasterPlan(true);
+                  new_plan_sp->SetIsControllingPlan(true);
                   new_plan_sp->SetOkayToDiscard(false);
                   new_plan_sp->SetPrivate(true);
                 }

lldb/source/Target/Thread.cpp

@@ -844,7 +844,7 @@ bool Thread::ShouldStop(Event *event_ptr) {
             // we're done, otherwise we forward this to the next plan in the
             // stack below.
             done_processing_current_plan =
-                (plan_ptr->IsMasterPlan() && !plan_ptr->OkayToDiscard());
+                (plan_ptr->IsControllingPlan() && !plan_ptr->OkayToDiscard());
           } else
             done_processing_current_plan = true;
 
@@ -882,11 +882,11 @@ bool Thread::ShouldStop(Event *event_ptr) {
                       current_plan->GetName());
           }
 
-          // If a Master Plan wants to stop, we let it. Otherwise, see if the
-          // plan's parent wants to stop.
+          // If a Controlling Plan wants to stop, we let it. Otherwise, see if
+          // the plan's parent wants to stop.
 
           PopPlan();
-          if (should_stop && current_plan->IsMasterPlan() &&
+          if (should_stop && current_plan->IsControllingPlan() &&
               !current_plan->OkayToDiscard()) {
             break;
           }
@@ -905,8 +905,8 @@ bool Thread::ShouldStop(Event *event_ptr) {
       should_stop = false;
   }
 
-  // One other potential problem is that we set up a master plan, then stop in
-  // before it is complete - for instance by hitting a breakpoint during a
+  // One other potential problem is that we set up a controlling plan, then stop
+  // in before it is complete - for instance by hitting a breakpoint during a
   // step-over - then do some step/finish/etc operations that wind up past the
   // end point condition of the initial plan.  We don't want to strand the
   // original plan on the stack, This code clears stale plans off the stack.
@@ -1214,7 +1214,7 @@ void Thread::DiscardThreadPlans(bool force) {
     GetPlans().DiscardAllPlans();
     return;
   }
-  GetPlans().DiscardConsultingMasterPlans();
+  GetPlans().DiscardConsultingControllingPlans();
 }
 
 Status Thread::UnwindInnermostExpression() {
@@ -1914,7 +1914,7 @@ Status Thread::StepIn(bool source_step,
           false, abort_other_plans, run_mode, error);
     }
 
-    new_plan_sp->SetIsMasterPlan(true);
+    new_plan_sp->SetIsControllingPlan(true);
     new_plan_sp->SetOkayToDiscard(false);
 
     // Why do we need to set the current thread by ID here???
@@ -1947,7 +1947,7 @@ Status Thread::StepOver(bool source_step,
           true, abort_other_plans, run_mode, error);
     }
 
-    new_plan_sp->SetIsMasterPlan(true);
+    new_plan_sp->SetIsControllingPlan(true);
     new_plan_sp->SetOkayToDiscard(false);
 
     // Why do we need to set the current thread by ID here???
@@ -1971,7 +1971,7 @@ Status Thread::StepOut() {
         abort_other_plans, nullptr, first_instruction, stop_other_threads,
         eVoteYes, eVoteNoOpinion, 0, error));
 
-    new_plan_sp->SetIsMasterPlan(true);
+    new_plan_sp->SetIsControllingPlan(true);
     new_plan_sp->SetOkayToDiscard(false);
 
     // Why do we need to set the current thread by ID here???

lldb/source/Target/ThreadPlan.cpp

@@ -26,8 +26,8 @@ ThreadPlan::ThreadPlan(ThreadPlanKind kind, const char *name, Thread &thread,
       m_takes_iteration_count(false), m_could_not_resolve_hw_bp(false),
       m_thread(&thread), m_kind(kind), m_name(name), m_plan_complete_mutex(),
       m_cached_plan_explains_stop(eLazyBoolCalculate), m_plan_complete(false),
-      m_plan_private(false), m_okay_to_discard(true), m_is_master_plan(false),
-      m_plan_succeeded(true) {
+      m_plan_private(false), m_okay_to_discard(true),
+      m_is_controlling_plan(false), m_plan_succeeded(true) {
   SetID(GetNextID());
 }
 
@@ -152,7 +152,7 @@ void ThreadPlan::DidPush() {}
 void ThreadPlan::DidPop() {}
 
 bool ThreadPlan::OkayToDiscard() {
-  return IsMasterPlan() ? m_okay_to_discard : true;
+  return IsControllingPlan() ? m_okay_to_discard : true;
 }
 
 lldb::StateType ThreadPlan::RunState() {

lldb/source/Target/ThreadPlanBase.cpp

@@ -40,7 +40,7 @@ ThreadPlanBase::ThreadPlanBase(Thread &thread)
 #endif
   new_tracer_sp->EnableTracing(thread.GetTraceEnabledState());
   SetThreadPlanTracer(new_tracer_sp);
-  SetIsMasterPlan(true);
+  SetIsControllingPlan(true);
 }
 
 ThreadPlanBase::~ThreadPlanBase() = default;
@@ -90,8 +90,8 @@ bool ThreadPlanBase::ShouldStop(Event *event_ptr) {
     case eStopReasonWatchpoint:
       if (stop_info_sp->ShouldStopSynchronous(event_ptr)) {
         // If we are going to stop for a breakpoint, then unship the other
-        // plans at this point.  Don't force the discard, however, so Master
-        // plans can stay in place if they want to.
+        // plans at this point.  Don't force the discard, however, so
+        // Controlling plans can stay in place if they want to.
         LLDB_LOGF(
             log,
             "Base plan discarding thread plans for thread tid = 0x%4.4" PRIx64

lldb/source/Target/ThreadPlanCallFunction.cpp

@@ -33,7 +33,7 @@ using namespace lldb_private;
 bool ThreadPlanCallFunction::ConstructorSetup(
     Thread &thread, ABI *&abi, lldb::addr_t &start_load_addr,
     lldb::addr_t &function_load_addr) {
-  SetIsMasterPlan(true);
+  SetIsControllingPlan(true);
   SetOkayToDiscard(false);
   SetPrivate(true);
 

lldb/source/Target/ThreadPlanCallOnFunctionExit.cpp

@@ -18,7 +18,7 @@ ThreadPlanCallOnFunctionExit::ThreadPlanCallOnFunctionExit(
                  ),
       m_callback(callback) {
   // We are not a user-generated plan.
-  SetIsMasterPlan(false);
+  SetIsControllingPlan(false);
 }
 
 void ThreadPlanCallOnFunctionExit::DidPush() {

lldb/source/Target/ThreadPlanCallUserExpression.cpp

@@ -39,7 +39,7 @@ ThreadPlanCallUserExpression::ThreadPlanCallUserExpression(
       m_user_expression_sp(user_expression_sp) {
   // User expressions are generally "User generated" so we should set them up
   // to stop when done.
-  SetIsMasterPlan(true);
+  SetIsControllingPlan(true);
   SetOkayToDiscard(false);
 }
 

lldb/source/Target/ThreadPlanPython.cpp

@@ -31,7 +31,7 @@ ThreadPlanPython::ThreadPlanPython(Thread &thread, const char *class_name,
                  eVoteNoOpinion, eVoteNoOpinion),
       m_class_name(class_name), m_args_data(args_data), m_did_push(false),
       m_stop_others(false) {
-  SetIsMasterPlan(true);
+  SetIsControllingPlan(true);
   SetOkayToDiscard(true);
   SetPrivate(false);
 }

lldb/source/Target/ThreadPlanStack.cpp

@@ -213,35 +213,35 @@ void ThreadPlanStack::DiscardAllPlans() {
   return;
 }
 
-void ThreadPlanStack::DiscardConsultingMasterPlans() {
+void ThreadPlanStack::DiscardConsultingControllingPlans() {
   std::lock_guard<std::recursive_mutex> guard(m_stack_mutex);
   while (true) {
-    int master_plan_idx;
+    int controlling_plan_idx;
     bool discard = true;
 
-    // Find the first master plan, see if it wants discarding, and if yes
+    // Find the first controlling plan, see if it wants discarding, and if yes
     // discard up to it.
-    for (master_plan_idx = m_plans.size() - 1; master_plan_idx >= 0;
-         master_plan_idx--) {
-      if (m_plans[master_plan_idx]->IsMasterPlan()) {
-        discard = m_plans[master_plan_idx]->OkayToDiscard();
+    for (controlling_plan_idx = m_plans.size() - 1; controlling_plan_idx >= 0;
+         controlling_plan_idx--) {
+      if (m_plans[controlling_plan_idx]->IsControllingPlan()) {
+        discard = m_plans[controlling_plan_idx]->OkayToDiscard();
         break;
       }
     }
 
-    // If the master plan doesn't want to get discarded, then we're done.
+    // If the controlling plan doesn't want to get discarded, then we're done.
     if (!discard)
       return;
 
     // First pop all the dependent plans:
-    for (int i = m_plans.size() - 1; i > master_plan_idx; i--) {
+    for (int i = m_plans.size() - 1; i > controlling_plan_idx; i--) {
       DiscardPlan();
     }
 
-    // Now discard the master plan itself.
+    // Now discard the controlling plan itself.
     // The bottom-most plan never gets discarded.  "OkayToDiscard" for it
     // means discard it's dependent plans, but not it...
-    if (master_plan_idx > 0) {
+    if (controlling_plan_idx > 0) {
       DiscardPlan();
     }
   }