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

#include "lldb/Target/SystemRuntime.h"

Inheritance diagram for lldb_private::SystemRuntime:

[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 Runtime &	operator= (const Runtime &)=delete

Process *	GetProcess ()

Target &	GetTargetRef ()

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

PluginInterface &	operator= (const PluginInterface &)=delete

Static Public Member Functions
static SystemRuntime *	FindPlugin (Process *process)
	Find a system runtime plugin for a given process.

Protected Attributes
std::vector< ConstString >	m_types

Protected Attributes inherited from lldb_private::Runtime
Process *	m_process

Private Member Functions
	SystemRuntime (const SystemRuntime &)=delete

const SystemRuntime &	operator= (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] dict Dictionary 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_item	The QueueItem that we will be completing.
[in]	item_ref	The 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.

◆ 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] process The 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_sp	The QueueItem that we are getting an extended backtrace for.
[in]	type	The 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]	thread	The thread to examine.
[in]	type	The 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_qaddr The 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_qaddr The 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_qaddr The 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] queue The 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_list This 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_sp The 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

Definition at line 298 of file SystemRuntime.h.

Referenced by GetExtendedBacktraceTypes(), and SystemRuntimeMacOSX::GetExtendedBacktraceTypes().

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

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SystemRuntime() [1/2]

◆ ~SystemRuntime()

◆ SystemRuntime() [2/2]

Member Function Documentation

◆ AddThreadExtendedInfoPacketHints()

◆ CompleteQueueItem()

◆ Detach()

◆ DidAttach()

◆ DidLaunch()

◆ FindPlugin()

◆ GetExtendedBacktraceForQueueItem()

◆ GetExtendedBacktraceThread()

◆ GetExtendedBacktraceTypes()

◆ GetLibdispatchQueueAddressFromThreadQAddress()

◆ GetQueueIDFromThreadQAddress()

◆ GetQueueKind()

◆ GetQueueNameFromThreadQAddress()

◆ ModulesDidLoad()

◆ operator=()

◆ PopulatePendingItemsForQueue()

◆ PopulateQueueList()

◆ SafeToCallFunctionsOnThisThread()

Member Data Documentation

◆ m_types