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

A plug-in interface definition class for system runtimes. More...

#include "lldb/Target/SystemRuntime.h"

Inheritance diagram for lldb_private::SystemRuntime:
Inheritance graph
[legend]

Public Member Functions

 SystemRuntime (Process *process)
 Construct with a process.
 
 ~SystemRuntime () override
 Destructor.
 
virtual void DidAttach ()
 Called after attaching to a process.
 
virtual void DidLaunch ()
 Called after launching a process.
 
void ModulesDidLoad (const ModuleList &module_list) override
 Called when modules have been loaded in the process.
 
virtual void Detach ()
 Called before detaching from a process.
 
virtual const std::vector< ConstString > & GetExtendedBacktraceTypes ()
 Return a list of thread origin extended backtraces that may be available.
 
virtual lldb::ThreadSP GetExtendedBacktraceThread (lldb::ThreadSP thread, ConstString type)
 Return a Thread which shows the origin of this thread's creation.
 
virtual lldb::ThreadSP GetExtendedBacktraceForQueueItem (lldb::QueueItemSP queue_item_sp, ConstString type)
 Get the extended backtrace thread for a QueueItem.
 
virtual void PopulateQueueList (lldb_private::QueueList &queue_list)
 Populate the Process' QueueList with libdispatch / GCD queues that exist.
 
virtual std::string GetQueueNameFromThreadQAddress (lldb::addr_t dispatch_qaddr)
 Get the queue name for a thread given a thread's dispatch_qaddr.
 
virtual lldb::queue_id_t GetQueueIDFromThreadQAddress (lldb::addr_t dispatch_qaddr)
 Get the QueueID for the libdispatch queue given the thread's dispatch_qaddr.
 
virtual lldb::addr_t GetLibdispatchQueueAddressFromThreadQAddress (lldb::addr_t dispatch_qaddr)
 Get the libdispatch_queue_t address for the queue given the thread's dispatch_qaddr.
 
virtual lldb::QueueKind GetQueueKind (lldb::addr_t dispatch_qaddr)
 Retrieve the Queue kind for the queue at a thread's dispatch_qaddr.
 
virtual void PopulatePendingItemsForQueue (lldb_private::Queue *queue)
 Get the pending work items for a libdispatch Queue.
 
virtual void CompleteQueueItem (lldb_private::QueueItem *queue_item, lldb::addr_t item_ref)
 Complete the fields in a QueueItem.
 
virtual void AddThreadExtendedInfoPacketHints (lldb_private::StructuredData::ObjectSP dict)
 Add key-value pairs to the StructuredData dictionary object with information debugserver may need when constructing the jThreadExtendedInfo packet.
 
virtual bool SafeToCallFunctionsOnThisThread (lldb::ThreadSP thread_sp)
 Determine whether it is safe to run an expression on a given thread.
 
- Public Member Functions inherited from lldb_private::Runtime
 Runtime (Process *process)
 
virtual ~Runtime ()=default
 
 Runtime (const Runtime &)=delete
 
const Runtimeoperator= (const Runtime &)=delete
 
ProcessGetProcess ()
 
TargetGetTargetRef ()
 
virtual void ModulesDidLoad (const ModuleList &module_list)=0
 Called when modules have been loaded in the process.
 
- Public Member Functions inherited from lldb_private::PluginInterface
 PluginInterface ()=default
 
virtual ~PluginInterface ()=default
 
virtual llvm::StringRef GetPluginName ()=0
 
 PluginInterface (const PluginInterface &)=delete
 
PluginInterfaceoperator= (const PluginInterface &)=delete
 

Static Public Member Functions

static SystemRuntimeFindPlugin (Process *process)
 Find a system runtime plugin for a given process.
 

Protected Attributes

std::vector< ConstStringm_types
 
- Protected Attributes inherited from lldb_private::Runtime
Processm_process
 

Private Member Functions

 SystemRuntime (const SystemRuntime &)=delete
 
const SystemRuntimeoperator= (const SystemRuntime &)=delete
 

Detailed Description

A plug-in interface definition class for system runtimes.

The system runtime plugins can collect information from the system libraries during a Process' lifetime and provide information about how objects/threads were originated.

For instance, a system runtime plugin use a breakpoint when threads are created to record the backtrace of where that thread was created. Later, when backtracing the created thread, it could extend the backtrace to show where it was originally created from.

The plugin will insert its own breakpoint when Created and start collecting information. Later when it comes time to augment a Thread, it can be asked to provide that information.

Definition at line 43 of file SystemRuntime.h.

Constructor & Destructor Documentation

◆ SystemRuntime() [1/2]

SystemRuntime::SystemRuntime ( Process process)

Construct with a process.

Definition at line 30 of file SystemRuntime.cpp.

◆ ~SystemRuntime()

SystemRuntime::~SystemRuntime ( )
overridedefault

Destructor.

The destructor is virtual since this class is designed to be inherited by the plug-in instance.

◆ SystemRuntime() [2/2]

lldb_private::SystemRuntime::SystemRuntime ( const SystemRuntime )
privatedelete

Member Function Documentation

◆ AddThreadExtendedInfoPacketHints()

virtual void lldb_private::SystemRuntime::AddThreadExtendedInfoPacketHints ( lldb_private::StructuredData::ObjectSP  dict)
inlinevirtual

Add key-value pairs to the StructuredData dictionary object with information debugserver may need when constructing the jThreadExtendedInfo packet.

Parameters
[out]dictDictionary to which key-value pairs should be added; they will be sent to the remote gdb server stub as arguments in the jThreadExtendedInfo request.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 277 of file SystemRuntime.h.

Referenced by lldb_private::process_gdb_remote::ProcessGDBRemote::GetExtendedInfoForThread().

◆ CompleteQueueItem()

virtual void lldb_private::SystemRuntime::CompleteQueueItem ( lldb_private::QueueItem queue_item,
lldb::addr_t  item_ref 
)
inlinevirtual

Complete the fields in a QueueItem.

PopulatePendingItemsForQueue() may not fill in all of the QueueItem details; when the remaining fields are needed, they will be fetched by call this method.

Parameters
[in]queue_itemThe QueueItem that we will be completing.
[in]item_refThe item_ref token that is needed to retrieve the rest of the information about the QueueItem.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 266 of file SystemRuntime.h.

Referenced by lldb_private::QueueItem::FetchEntireItem().

◆ Detach()

void SystemRuntime::Detach ( )
virtual

Called before detaching from a process.

This will give a SystemRuntime plugin a chance to free any resources in the inferior process before we detach.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 38 of file SystemRuntime.cpp.

◆ DidAttach()

void SystemRuntime::DidAttach ( )
virtual

Called after attaching to a process.

Allow the SystemRuntime plugin to execute some code after attaching to a process.

Definition at line 34 of file SystemRuntime.cpp.

Referenced by lldb_private::Process::CompleteAttach(), and lldb_private::Process::LoadCore().

◆ DidLaunch()

void SystemRuntime::DidLaunch ( )
virtual

Called after launching a process.

Allow the SystemRuntime plugin to execute some code after launching a process.

Definition at line 36 of file SystemRuntime.cpp.

Referenced by lldb_private::Process::LaunchPrivate().

◆ FindPlugin()

SystemRuntime * SystemRuntime::FindPlugin ( Process process)
static

Find a system runtime plugin for a given process.

Scans the installed SystemRuntime plugins and tries to find an instance that can be used to track image changes in process.

Parameters
[in]processThe process for which to try and locate a system runtime plugin instance.

Definition at line 17 of file SystemRuntime.cpp.

References lldb_private::PluginManager::GetSystemRuntimeCreateCallbackAtIndex().

Referenced by lldb_private::Process::GetSystemRuntime().

◆ GetExtendedBacktraceForQueueItem()

virtual lldb::ThreadSP lldb_private::SystemRuntime::GetExtendedBacktraceForQueueItem ( lldb::QueueItemSP  queue_item_sp,
ConstString  type 
)
inlinevirtual

Get the extended backtrace thread for a QueueItem.

A QueueItem represents a function/block that will be executed on a libdispatch queue in the future, or it represents a function/block that is currently executing on a thread.

This method will report a thread backtrace of the function that enqueued it originally, if possible.

Parameters
[in]queue_item_spThe QueueItem that we are getting an extended backtrace for.
[in]typeThe type of extended backtrace to fetch. The types supported are returned from SystemRuntime::GetExtendedBacktraceTypes.
Returns
If an extended backtrace is available, it is returned. Else an empty ThreadSP is returned.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 158 of file SystemRuntime.h.

◆ GetExtendedBacktraceThread()

ThreadSP SystemRuntime::GetExtendedBacktraceThread ( lldb::ThreadSP  thread,
ConstString  type 
)
virtual

Return a Thread which shows the origin of this thread's creation.

This likely returns a HistoryThread which shows how thread was originally created (e.g. "pthread" type), or how the work that is currently executing on it was originally enqueued (e.g. "libdispatch" type).

There may be a chain of thread-origins; it may be informative to the end user to query the returned ThreadSP for its origins as well.

Parameters
[in]threadThe thread to examine.
[in]typeThe type of thread origin being requested. The types supported are returned from SystemRuntime::GetExtendedBacktraceTypes.
Returns
A ThreadSP which will have a StackList of frames. This Thread will not appear in the Process' list of current threads. Normal thread operations like stepping will not be available. This is a historical view thread and may be only useful for showing a backtrace.

An empty ThreadSP will be returned if no thread origin is available.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 46 of file SystemRuntime.cpp.

Referenced by CommandObjectThreadBacktrace::DoExtendedBacktrace(), and lldb::SBThread::GetExtendedBacktraceThread().

◆ GetExtendedBacktraceTypes()

const std::vector< ConstString > & SystemRuntime::GetExtendedBacktraceTypes ( )
virtual

Return a list of thread origin extended backtraces that may be available.

A System Runtime may be able to provide a backtrace of when this thread was originally created. Furthermore, it may be able to provide that extended backtrace for different styles of creation. On a system with both pthreads and libdispatch, aka Grand Central Dispatch, queues, the system runtime may be able to provide the pthread creation of the thread and it may also be able to provide the backtrace of when this GCD queue work block was enqueued. The caller may request these different origins by name.

The names will be provided in the order that they are most likely to be requested. For instance, a most natural order may be to request the GCD libdispatch queue origin. If there is none, then request the pthread origin.

Returns
A vector of ConstStrings with names like "pthread" or "libdispatch". An empty vector may be returned if no thread origin extended backtrace capabilities are available.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 42 of file SystemRuntime.cpp.

References m_types.

Referenced by CommandObjectThreadBacktrace::DoExtendedBacktrace(), lldb::SBProcess::GetExtendedBacktraceTypeAtIndex(), and lldb::SBProcess::GetNumExtendedBacktraceTypes().

◆ GetLibdispatchQueueAddressFromThreadQAddress()

virtual lldb::addr_t lldb_private::SystemRuntime::GetLibdispatchQueueAddressFromThreadQAddress ( lldb::addr_t  dispatch_qaddr)
inlinevirtual

Get the libdispatch_queue_t address for the queue given the thread's dispatch_qaddr.

On systems using libdispatch queues, a thread may be associated with a queue. There will be a call to get the thread's dispatch_qaddr. Given the thread's dispatch_qaddr, find the libdispatch_queue_t address and return it.

Parameters
[in]dispatch_qaddrThe address of the dispatch_qaddr pointer for this thread.
Returns
The libdispatch_queue_t address, or LLDB_INVALID_ADDRESS if unavailable/not found.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 228 of file SystemRuntime.h.

References LLDB_INVALID_ADDRESS.

Referenced by lldb_private::process_gdb_remote::ThreadGDBRemote::GetQueueLibdispatchQueueAddress().

◆ GetQueueIDFromThreadQAddress()

virtual lldb::queue_id_t lldb_private::SystemRuntime::GetQueueIDFromThreadQAddress ( lldb::addr_t  dispatch_qaddr)
inlinevirtual

Get the QueueID for the libdispatch queue given the thread's dispatch_qaddr.

On systems using libdispatch queues, a thread may be associated with a queue. There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr we will find the address of this thread's dispatch_queue_t structure. Given the address of the dispatch_queue_t structure for a thread, get the queue ID and return it.

Parameters
[in]dispatch_qaddrThe address of the dispatch_qaddr pointer for this thread.
Returns
The queue ID, or if it could not be retrieved, LLDB_INVALID_QUEUE_ID.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 209 of file SystemRuntime.h.

References LLDB_INVALID_QUEUE_ID.

Referenced by lldb_private::process_gdb_remote::ThreadGDBRemote::GetQueueID().

◆ GetQueueKind()

virtual lldb::QueueKind lldb_private::SystemRuntime::GetQueueKind ( lldb::addr_t  dispatch_qaddr)
inlinevirtual

Retrieve the Queue kind for the queue at a thread's dispatch_qaddr.

Retrieve the Queue kind - either eQueueKindSerial or eQueueKindConcurrent, indicating that this queue processes work items serially or concurrently.

Returns
The Queue kind, if it could be read, else eQueueKindUnknown.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 240 of file SystemRuntime.h.

References lldb::eQueueKindUnknown.

Referenced by lldb_private::process_gdb_remote::ThreadGDBRemote::GetQueueKind().

◆ GetQueueNameFromThreadQAddress()

virtual std::string lldb_private::SystemRuntime::GetQueueNameFromThreadQAddress ( lldb::addr_t  dispatch_qaddr)
inlinevirtual

Get the queue name for a thread given a thread's dispatch_qaddr.

On systems using libdispatch queues, a thread may be associated with a queue. There will be a call to get the thread's dispatch_qaddr. At the dispatch_qaddr we will find the address of this thread's dispatch_queue_t structure. Given the address of the dispatch_queue_t structure for a thread, get the queue name and return it.

Parameters
[in]dispatch_qaddrThe address of the dispatch_qaddr pointer for this thread.
Returns
The string of this queue's name. An empty string is returned if the name could not be found.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 190 of file SystemRuntime.h.

Referenced by lldb_private::process_gdb_remote::ThreadGDBRemote::GetQueueName().

◆ ModulesDidLoad()

void SystemRuntime::ModulesDidLoad ( const ModuleList module_list)
overridevirtual

Called when modules have been loaded in the process.

Allow the SystemRuntime plugin to enable logging features in the system runtime libraries.

Implements lldb_private::Runtime.

Definition at line 40 of file SystemRuntime.cpp.

Referenced by lldb_private::Process::ModulesDidLoad().

◆ operator=()

const SystemRuntime & lldb_private::SystemRuntime::operator= ( const SystemRuntime )
privatedelete

◆ PopulatePendingItemsForQueue()

virtual void lldb_private::SystemRuntime::PopulatePendingItemsForQueue ( lldb_private::Queue queue)
inlinevirtual

Get the pending work items for a libdispatch Queue.

If this system/process is using libdispatch and the runtime can do so, retrieve the list of pending work items for the specified Queue and add it to the Queue.

Parameters
[in]queueThe queue of interest.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 252 of file SystemRuntime.h.

◆ PopulateQueueList()

virtual void lldb_private::SystemRuntime::PopulateQueueList ( lldb_private::QueueList queue_list)
inlinevirtual

Populate the Process' QueueList with libdispatch / GCD queues that exist.

When process execution is paused, the SystemRuntime may be called to fill in the list of Queues that currently exist.

Parameters
[out]queue_listThis QueueList will be cleared, and any queues that currently exist will be added. An empty QueueList will be returned if no queues exist or if this Systemruntime does not support libdispatch queues.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 173 of file SystemRuntime.h.

◆ SafeToCallFunctionsOnThisThread()

virtual bool lldb_private::SystemRuntime::SafeToCallFunctionsOnThisThread ( lldb::ThreadSP  thread_sp)
inlinevirtual

Determine whether it is safe to run an expression on a given thread.

If a system must not run functions on a thread in some particular state, this method gives a way for it to flag that the expression should not be run.

Parameters
[in]thread_spThe thread we want to run the expression on.
Returns
True will be returned if there are no known problems with running an expression on this thread. False means that the inferior function call should not be made on this thread.

Reimplemented in SystemRuntimeMacOSX.

Definition at line 293 of file SystemRuntime.h.

Referenced by lldb_private::Thread::SafeToCallFunctions().

Member Data Documentation

◆ m_types

std::vector<ConstString> lldb_private::SystemRuntime::m_types
protected

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