diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/python-reference.rst @@ -442,7 +442,7 @@ 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: diff --git a/lldb/include/lldb/Target/Thread.h b/lldb/include/lldb/Target/Thread.h --- a/lldb/include/lldb/Target/Thread.h +++ b/lldb/include/lldb/Target/Thread.h @@ -1015,7 +1015,8 @@ /// 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); diff --git a/lldb/include/lldb/Target/ThreadPlan.h b/lldb/include/lldb/Target/ThreadPlan.h --- a/lldb/include/lldb/Target/ThreadPlan.h +++ b/lldb/include/lldb/Target/ThreadPlan.h @@ -144,39 +144,42 @@ // 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 @@ // // 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 @@ 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 @@ 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 @@ 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; diff --git a/lldb/include/lldb/Target/ThreadPlanStack.h b/lldb/include/lldb/Target/ThreadPlanStack.h --- a/lldb/include/lldb/Target/ThreadPlanStack.h +++ b/lldb/include/lldb/Target/ThreadPlanStack.h @@ -60,7 +60,7 @@ void DiscardAllPlans(); - void DiscardConsultingMasterPlans(); + void DiscardConsultingControllingPlans(); lldb::ThreadPlanSP GetCurrentPlan() const; diff --git a/lldb/source/API/SBThread.cpp b/lldb/source/API/SBThread.cpp --- a/lldb/source/API/SBThread.cpp +++ b/lldb/source/API/SBThread.cpp @@ -513,10 +513,10 @@ 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); } diff --git a/lldb/source/Commands/CommandObjectThread.cpp b/lldb/source/Commands/CommandObjectThread.cpp --- a/lldb/source/Commands/CommandObjectThread.cpp +++ b/lldb/source/Commands/CommandObjectThread.cpp @@ -526,12 +526,12 @@ 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 @@ 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); diff --git a/lldb/source/Expression/FunctionCaller.cpp b/lldb/source/Expression/FunctionCaller.cpp --- a/lldb/source/Expression/FunctionCaller.cpp +++ b/lldb/source/Expression/FunctionCaller.cpp @@ -254,7 +254,7 @@ 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; } diff --git a/lldb/source/Target/Process.cpp b/lldb/source/Target/Process.cpp --- a/lldb/source/Target/Process.cpp +++ b/lldb/source/Target/Process.cpp @@ -4526,7 +4526,8 @@ 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 @@ : 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 @@ 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 @@ 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 @@ 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 diff --git a/lldb/source/Target/StopInfo.cpp b/lldb/source/Target/StopInfo.cpp --- a/lldb/source/Target/StopInfo.cpp +++ b/lldb/source/Target/StopInfo.cpp @@ -764,7 +764,7 @@ 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); } diff --git a/lldb/source/Target/Thread.cpp b/lldb/source/Target/Thread.cpp --- a/lldb/source/Target/Thread.cpp +++ b/lldb/source/Target/Thread.cpp @@ -844,7 +844,7 @@ // 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 @@ 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 @@ 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 @@ GetPlans().DiscardAllPlans(); return; } - GetPlans().DiscardConsultingMasterPlans(); + GetPlans().DiscardConsultingControllingPlans(); } Status Thread::UnwindInnermostExpression() { @@ -1914,7 +1914,7 @@ 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 @@ 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 @@ 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??? diff --git a/lldb/source/Target/ThreadPlan.cpp b/lldb/source/Target/ThreadPlan.cpp --- a/lldb/source/Target/ThreadPlan.cpp +++ b/lldb/source/Target/ThreadPlan.cpp @@ -26,8 +26,8 @@ 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::DidPop() {} bool ThreadPlan::OkayToDiscard() { - return IsMasterPlan() ? m_okay_to_discard : true; + return IsControllingPlan() ? m_okay_to_discard : true; } lldb::StateType ThreadPlan::RunState() { diff --git a/lldb/source/Target/ThreadPlanBase.cpp b/lldb/source/Target/ThreadPlanBase.cpp --- a/lldb/source/Target/ThreadPlanBase.cpp +++ b/lldb/source/Target/ThreadPlanBase.cpp @@ -40,7 +40,7 @@ #endif new_tracer_sp->EnableTracing(thread.GetTraceEnabledState()); SetThreadPlanTracer(new_tracer_sp); - SetIsMasterPlan(true); + SetIsControllingPlan(true); } ThreadPlanBase::~ThreadPlanBase() = default; @@ -90,8 +90,8 @@ 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 diff --git a/lldb/source/Target/ThreadPlanCallFunction.cpp b/lldb/source/Target/ThreadPlanCallFunction.cpp --- a/lldb/source/Target/ThreadPlanCallFunction.cpp +++ b/lldb/source/Target/ThreadPlanCallFunction.cpp @@ -33,7 +33,7 @@ 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); diff --git a/lldb/source/Target/ThreadPlanCallOnFunctionExit.cpp b/lldb/source/Target/ThreadPlanCallOnFunctionExit.cpp --- a/lldb/source/Target/ThreadPlanCallOnFunctionExit.cpp +++ b/lldb/source/Target/ThreadPlanCallOnFunctionExit.cpp @@ -18,7 +18,7 @@ ), m_callback(callback) { // We are not a user-generated plan. - SetIsMasterPlan(false); + SetIsControllingPlan(false); } void ThreadPlanCallOnFunctionExit::DidPush() { diff --git a/lldb/source/Target/ThreadPlanCallUserExpression.cpp b/lldb/source/Target/ThreadPlanCallUserExpression.cpp --- a/lldb/source/Target/ThreadPlanCallUserExpression.cpp +++ b/lldb/source/Target/ThreadPlanCallUserExpression.cpp @@ -39,7 +39,7 @@ 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); } diff --git a/lldb/source/Target/ThreadPlanPython.cpp b/lldb/source/Target/ThreadPlanPython.cpp --- a/lldb/source/Target/ThreadPlanPython.cpp +++ b/lldb/source/Target/ThreadPlanPython.cpp @@ -31,7 +31,7 @@ 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); } diff --git a/lldb/source/Target/ThreadPlanStack.cpp b/lldb/source/Target/ThreadPlanStack.cpp --- a/lldb/source/Target/ThreadPlanStack.cpp +++ b/lldb/source/Target/ThreadPlanStack.cpp @@ -213,35 +213,35 @@ return; } -void ThreadPlanStack::DiscardConsultingMasterPlans() { +void ThreadPlanStack::DiscardConsultingControllingPlans() { std::lock_guard 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(); } }