LLDB  mainline
Public Member Functions | Protected Attributes | List of all members
lldb_private::ExecutionContextRef Class Reference

Execution context objects refer to objects in the execution of the program that is being debugged. More...

#include <ExecutionContext.h>

Collaboration diagram for lldb_private::ExecutionContextRef:
Collaboration graph
[legend]

Public Member Functions

 ExecutionContextRef ()
 Default Constructor. More...
 
 ExecutionContextRef (const ExecutionContextRef &rhs)
 Copy Constructor. More...
 
 ExecutionContextRef (const ExecutionContext *exe_ctx_ptr)
 Construct using an ExecutionContext object that might be nullptr. More...
 
 ExecutionContextRef (const ExecutionContext &exe_ctx)
 Construct using an ExecutionContext object. More...
 
 ExecutionContextRef (Target *target, bool adopt_selected)
 Construct using the target and all the selected items inside of it (the process and its selected thread, and the thread's selected frame). More...
 
 ExecutionContextRef (ExecutionContextScope *exe_scope)
 Construct using an execution context scope. More...
 
 ExecutionContextRef (ExecutionContextScope &exe_scope)
 Construct using an execution context scope. More...
 
 ~ExecutionContextRef ()
 
ExecutionContextRefoperator= (const ExecutionContextRef &rhs)
 Assignment operator. More...
 
ExecutionContextRefoperator= (const ExecutionContext &exe_ctx)
 Assignment operator from a ExecutionContext. More...
 
void Clear ()
 Clear the object's state. More...
 
void SetTargetSP (const lldb::TargetSP &target_sp)
 Set accessor that creates a weak reference to the target referenced in target_sp. More...
 
void SetProcessSP (const lldb::ProcessSP &process_sp)
 Set accessor that creates a weak reference to the process referenced in process_sp. More...
 
void SetThreadSP (const lldb::ThreadSP &thread_sp)
 Set accessor that creates a weak reference to the thread referenced in thread_sp. More...
 
void SetFrameSP (const lldb::StackFrameSP &frame_sp)
 Set accessor that creates a weak reference to the frame referenced in frame_sp. More...
 
void SetTargetPtr (Target *target, bool adopt_selected)
 
void SetProcessPtr (Process *process)
 
void SetThreadPtr (Thread *thread)
 
void SetFramePtr (StackFrame *frame)
 
lldb::TargetSP GetTargetSP () const
 Get accessor that creates a strong reference from the weak target reference contained in this object. More...
 
lldb::ProcessSP GetProcessSP () const
 Get accessor that creates a strong reference from the weak process reference contained in this object. More...
 
lldb::ThreadSP GetThreadSP () const
 Get accessor that creates a strong reference from the weak thread reference contained in this object. More...
 
lldb::StackFrameSP GetFrameSP () const
 Get accessor that creates a strong reference from the weak frame reference contained in this object. More...
 
ExecutionContext Lock (bool thread_and_frame_only_if_stopped) const
 Create an ExecutionContext object from this object. More...
 
bool HasThreadRef () const
 Returns true if this object has a weak reference to a thread. More...
 
bool HasFrameRef () const
 Returns true if this object has a weak reference to a frame. More...
 
void ClearThread ()
 
void ClearFrame ()
 

Protected Attributes

lldb::TargetWP m_target_wp
 A weak reference to a target. More...
 
lldb::ProcessWP m_process_wp
 A weak reference to a process. More...
 
lldb::ThreadWP m_thread_wp
 A weak reference to a thread. More...
 
lldb::tid_t m_tid
 The thread ID that this object refers to in case the backing object changes. More...
 
StackID m_stack_id
 The stack ID that this object refers to in case the backing object changes. More...
 

Detailed Description

Execution context objects refer to objects in the execution of the program that is being debugged.

The consist of one or more of the following objects: target, process, thread, and frame. Many objects in the debugger need to track different executions contexts. For example, a local function variable might have an execution context that refers to a stack frame. A global or static variable might refer to a target since a stack frame isn't required in order to evaluate a global or static variable (a process isn't necessarily needed for a global variable since we might be able to read the variable value from a data section in one of the object files in a target). There are two types of objects that hold onto execution contexts: ExecutionContextRef and ExecutionContext. Both of these objects are described below.

Not all objects in an ExecutionContext objects will be valid. If you want to refer strongly (ExecutionContext) or weakly (ExecutionContextRef) to a process, then only the process and target references will be valid. For threads, only the thread, process and target references will be filled in. For frames, all of the objects will be filled in.

These classes are designed to be used as baton objects that get passed to a wide variety of functions that require execution contexts. "lldb/Target/ExecutionContext.h" A class that holds a weak reference to an execution context.

ExecutionContextRef objects are designed to hold onto an execution context that might change over time. For example, if an object wants to refer to a stack frame, it should hold onto an ExecutionContextRef to a frame object. The backing object that represents the stack frame might change over time and instances of this object can track the logical object that refers to a frame even if it does change.

These objects also don't keep execution objects around longer than they should since they use weak pointers. For example if an object refers to a stack frame and a stack frame is no longer in a thread, then a ExecutionContextRef object that refers to that frame will not be able to get a shared pointer to those objects since they are no longer around.

ExecutionContextRef objects can also be used as objects in classes that want to track a "previous execution context". Since the weak references to the execution objects (target, process, thread and frame) don't keep these objects around, they are safe to keep around.

The general rule of thumb is all long lived objects that want to refer to execution contexts should use ExecutionContextRef objects. The ExecutionContext class is used to temporarily get shared pointers to any execution context objects that are still around so they are guaranteed to exist during a function that requires the objects. ExecutionContext objects should NOT be used for long term storage since they will keep objects alive with extra shared pointer references to these objects.

Definition at line 72 of file ExecutionContext.h.

Constructor & Destructor Documentation

◆ ExecutionContextRef() [1/7]

ExecutionContextRef::ExecutionContextRef ( )

Default Constructor.

Definition at line 397 of file ExecutionContext.cpp.

◆ ExecutionContextRef() [2/7]

ExecutionContextRef::ExecutionContextRef ( const ExecutionContextRef rhs)

Copy Constructor.

Definition at line 420 of file ExecutionContext.cpp.

References operator=().

◆ ExecutionContextRef() [3/7]

ExecutionContextRef::ExecutionContextRef ( const ExecutionContext exe_ctx_ptr)

Construct using an ExecutionContext object that might be nullptr.

If exe_ctx_ptr is valid, then make weak references to any valid objects in the ExecutionContext, otherwise no weak references to any execution context objects will be made.

Definition at line 401 of file ExecutionContext.cpp.

◆ ExecutionContextRef() [4/7]

ExecutionContextRef::ExecutionContextRef ( const ExecutionContext exe_ctx)

Construct using an ExecutionContext object.

Make weak references to any valid objects in the ExecutionContext.

Definition at line 408 of file ExecutionContext.cpp.

◆ ExecutionContextRef() [5/7]

ExecutionContextRef::ExecutionContextRef ( Target target,
bool  adopt_selected 
)

Construct using the target and all the selected items inside of it (the process and its selected thread, and the thread's selected frame).

If there is no selected thread, default to the first thread If there is no selected frame, default to the first frame.

Definition at line 414 of file ExecutionContext.cpp.

References SetTargetPtr().

◆ ExecutionContextRef() [6/7]

lldb_private::ExecutionContextRef::ExecutionContextRef ( ExecutionContextScope exe_scope)

Construct using an execution context scope.

If the ExecutionContextScope object is valid and refers to a frame, make weak references too the frame, thread, process and target. If the ExecutionContextScope object is valid and refers to a thread, make weak references too the thread, process and target. If the ExecutionContextScope object is valid and refers to a process, make weak references too the process and target. If the ExecutionContextScope object is valid and refers to a target, make weak references too the target.

◆ ExecutionContextRef() [7/7]

lldb_private::ExecutionContextRef::ExecutionContextRef ( ExecutionContextScope exe_scope)

Construct using an execution context scope.

If the ExecutionContextScope object refers to a frame, make weak references too the frame, thread, process and target. If the ExecutionContextScope object refers to a thread, make weak references too the thread, process and target. If the ExecutionContextScope object refers to a process, make weak references too the process and target. If the ExecutionContextScope object refers to a target, make weak references too the target.

◆ ~ExecutionContextRef()

ExecutionContextRef::~ExecutionContextRef ( )
default

Referenced by Clear().

Member Function Documentation

◆ Clear()

void ExecutionContextRef::Clear ( )

Clear the object's state.

Sets the process and thread to nullptr, and the frame index to an invalid value.

Definition at line 455 of file ExecutionContext.cpp.

References ClearFrame(), ClearThread(), m_process_wp, m_target_wp, and ~ExecutionContextRef().

Referenced by lldb_private::StoppointCallbackContext::Clear(), SetFramePtr(), and SetTargetPtr().

◆ ClearFrame()

void lldb_private::ExecutionContextRef::ClearFrame ( )
inline

Definition at line 259 of file ExecutionContext.h.

References lldb_private::StackID::Clear(), and m_stack_id.

Referenced by Clear(), and SetFrameSP().

◆ ClearThread()

void lldb_private::ExecutionContextRef::ClearThread ( )
inline

Definition at line 254 of file ExecutionContext.h.

References LLDB_INVALID_THREAD_ID, m_thread_wp, and m_tid.

Referenced by Clear(), SetFrameSP(), SetThreadPtr(), and SetThreadSP().

◆ GetFrameSP()

lldb::StackFrameSP ExecutionContextRef::GetFrameSP ( ) const

Get accessor that creates a strong reference from the weak frame reference contained in this object.

Returns
A shared pointer to a frame that is not guaranteed to be valid.

Definition at line 606 of file ExecutionContext.cpp.

References GetThreadSP(), lldb_private::StackID::IsValid(), and m_stack_id.

Referenced by lldb_private::ExecutionContext::ExecutionContext(), lldb_private::ValueObject::GetFrameSP(), and lldb_private::ValueObject::EvaluationPoint::~EvaluationPoint().

◆ GetProcessSP()

lldb::ProcessSP ExecutionContextRef::GetProcessSP ( ) const

◆ GetTargetSP()

lldb::TargetSP ExecutionContextRef::GetTargetSP ( ) const

Get accessor that creates a strong reference from the weak target reference contained in this object.

Returns
A shared pointer to a target that is not guaranteed to be valid.

Definition at line 567 of file ExecutionContext.cpp.

References m_target_wp.

Referenced by lldb_private::formatters::CMTimeSummaryProvider(), lldb_private::ExecutionContext::ExecutionContext(), and lldb_private::ValueObject::GetTargetSP().

◆ GetThreadSP()

lldb::ThreadSP ExecutionContextRef::GetThreadSP ( ) const

◆ HasFrameRef()

bool lldb_private::ExecutionContextRef::HasFrameRef ( ) const
inline

Returns true if this object has a weak reference to a frame.

The return value is only an indication of whether this object has a weak reference and does not indicate whether the weak reference is valid or not.

Definition at line 252 of file ExecutionContext.h.

References lldb_private::StackID::IsValid(), and m_stack_id.

Referenced by lldb_private::ValueObjectVariable::IsInScope(), and lldb_private::ValueObject::EvaluationPoint::~EvaluationPoint().

◆ HasThreadRef()

bool lldb_private::ExecutionContextRef::HasThreadRef ( ) const
inline

Returns true if this object has a weak reference to a thread.

The return value is only an indication of whether this object has a weak reference and does not indicate whether the weak reference is valid or not.

Definition at line 247 of file ExecutionContext.h.

References LLDB_INVALID_THREAD_ID, and m_tid.

Referenced by lldb_private::ValueObject::EvaluationPoint::~EvaluationPoint().

◆ Lock()

ExecutionContext ExecutionContextRef::Lock ( bool  thread_and_frame_only_if_stopped) const

Create an ExecutionContext object from this object.

Create strong references to any execution context objects that are still valid. Any of the returned shared pointers in the ExecutionContext objects is not guaranteed to be valid.

Returns
An execution context object that has strong references to any valid weak references in this object.

Definition at line 616 of file ExecutionContext.cpp.

Referenced by lldb::SBCommandInterpreter::HandleCommand(), lldb::SBCommandInterpreter::HandleCommandsFromFile(), and lldb_private::ValueObject::EvaluationPoint::~EvaluationPoint().

◆ operator=() [1/2]

ExecutionContextRef & ExecutionContextRef::operator= ( const ExecutionContextRef rhs)

Assignment operator.

Copy all weak references in rhs.

Definition at line 426 of file ExecutionContext.cpp.

References m_process_wp, m_stack_id, m_target_wp, m_thread_wp, and m_tid.

Referenced by ExecutionContextRef().

◆ operator=() [2/2]

ExecutionContextRef & ExecutionContextRef::operator= ( const ExecutionContext exe_ctx)

◆ SetFramePtr()

void ExecutionContextRef::SetFramePtr ( StackFrame frame)

Definition at line 560 of file ExecutionContext.cpp.

References Clear(), and SetFrameSP().

Referenced by lldb_private::ExecutionContext::GetFrameSP().

◆ SetFrameSP()

void ExecutionContextRef::SetFrameSP ( const lldb::StackFrameSP &  frame_sp)

Set accessor that creates a weak reference to the frame referenced in frame_sp.

If frame_sp is valid this object will create a weak reference to that object, otherwise any previous frame weak reference contained in this object will be reset.

Only the weak reference to the frame will be updated, no other weak references will be modified. If you want this execution context to make a weak reference to the frame's thread, process and target, use the ExecutionContextRef::SetContext() functions.

See also
ExecutionContextRef::SetContext(const lldb::StackFrameSP &)

Definition at line 490 of file ExecutionContext.cpp.

References ClearFrame(), ClearThread(), m_process_wp, m_stack_id, m_target_wp, and SetThreadSP().

Referenced by lldb_private::ValueObject::EvaluationPoint::EvaluationPoint(), lldb_private::ExecutionContext::GetFrameSP(), SetFramePtr(), and SetTargetPtr().

◆ SetProcessPtr()

void ExecutionContextRef::SetProcessPtr ( Process process)

◆ SetProcessSP()

void ExecutionContextRef::SetProcessSP ( const lldb::ProcessSP &  process_sp)

Set accessor that creates a weak reference to the process referenced in process_sp.

If process_sp is valid this object will create a weak reference to that object, otherwise any previous process weak reference contained in this object will be reset.

Only the weak reference to the process will be updated, no other weak references will be modified. If you want this execution context to make a weak reference to the target, use the ExecutionContextRef::SetContext() functions.

See also
ExecutionContextRef::SetContext(const lldb::ProcessSP &)

Definition at line 468 of file ExecutionContext.cpp.

References m_process_wp, m_target_wp, and SetTargetSP().

Referenced by lldb_private::ValueObject::EvaluationPoint::EvaluationPoint(), lldb_private::ExecutionContext::GetFrameSP(), SetProcessPtr(), and SetThreadSP().

◆ SetTargetPtr()

void ExecutionContextRef::SetTargetPtr ( Target target,
bool  adopt_selected 
)

◆ SetTargetSP()

void ExecutionContextRef::SetTargetSP ( const lldb::TargetSP &  target_sp)

Set accessor that creates a weak reference to the target referenced in target_sp.

If target_sp is valid this object will create a weak reference to that object, otherwise any previous target weak reference contained in this object will be reset.

Only the weak reference to the target will be updated, no other weak references will be modified. If you want this execution context to make a weak reference to the target's process, use the ExecutionContextRef::SetContext() functions.

See also
ExecutionContextRef::SetContext(const lldb::TargetSP &, bool)

Definition at line 464 of file ExecutionContext.cpp.

References m_target_wp.

Referenced by lldb_private::ValueObject::EvaluationPoint::EvaluationPoint(), lldb_private::ExecutionContext::GetFrameSP(), and SetProcessSP().

◆ SetThreadPtr()

void ExecutionContextRef::SetThreadPtr ( Thread thread)

◆ SetThreadSP()

void ExecutionContextRef::SetThreadSP ( const lldb::ThreadSP &  thread_sp)

Set accessor that creates a weak reference to the thread referenced in thread_sp.

If thread_sp is valid this object will create a weak reference to that object, otherwise any previous thread weak reference contained in this object will be reset.

Only the weak reference to the thread will be updated, no other weak references will be modified. If you want this execution context to make a weak reference to the thread's process and target, use the ExecutionContextRef::SetContext() functions.

See also
ExecutionContextRef::SetContext(const lldb::ThreadSP &)

Definition at line 478 of file ExecutionContext.cpp.

References ClearThread(), m_process_wp, m_target_wp, m_thread_wp, m_tid, and SetProcessSP().

Referenced by lldb_private::ValueObject::EvaluationPoint::EvaluationPoint(), lldb_private::ExecutionContext::GetFrameSP(), SetFrameSP(), SetTargetPtr(), and SetThreadPtr().

Member Data Documentation

◆ m_process_wp

lldb::ProcessWP lldb_private::ExecutionContextRef::m_process_wp
protected

A weak reference to a process.

Definition at line 264 of file ExecutionContext.h.

Referenced by Clear(), GetProcessSP(), operator=(), SetFrameSP(), SetProcessPtr(), SetProcessSP(), SetTargetPtr(), SetThreadPtr(), and SetThreadSP().

◆ m_stack_id

StackID lldb_private::ExecutionContextRef::m_stack_id
protected

The stack ID that this object refers to in case the backing object changes.

Definition at line 268 of file ExecutionContext.h.

Referenced by ClearFrame(), GetFrameSP(), HasFrameRef(), operator=(), and SetFrameSP().

◆ m_target_wp

lldb::TargetWP lldb_private::ExecutionContextRef::m_target_wp
protected

A weak reference to a target.

Definition at line 263 of file ExecutionContext.h.

Referenced by Clear(), GetTargetSP(), operator=(), SetFrameSP(), SetProcessPtr(), SetProcessSP(), SetTargetPtr(), SetTargetSP(), SetThreadPtr(), and SetThreadSP().

◆ m_thread_wp

lldb::ThreadWP lldb_private::ExecutionContextRef::m_thread_wp
mutableprotected

A weak reference to a thread.

Definition at line 265 of file ExecutionContext.h.

Referenced by ClearThread(), GetThreadSP(), operator=(), and SetThreadSP().

◆ m_tid

lldb::tid_t lldb_private::ExecutionContextRef::m_tid
protected

The thread ID that this object refers to in case the backing object changes.

Definition at line 266 of file ExecutionContext.h.

Referenced by ClearThread(), GetThreadSP(), HasThreadRef(), operator=(), and SetThreadSP().


The documentation for this class was generated from the following files: