Plugin that supports process-related structured data sent asynchronously from the debug monitor (e.g. More...

#include <StructuredDataPlugin.h>

Inheritance diagram for lldb_private::StructuredDataPlugin:

[legend]

Public Member Functions
	~StructuredDataPlugin () override

lldb::ProcessSP	GetProcess () const

virtual bool	SupportsStructuredDataType (llvm::StringRef type_name)=0
	Return whether this plugin supports the given StructuredData feature.

virtual void	HandleArrivalOfStructuredData (Process &process, llvm::StringRef type_name, const StructuredData::ObjectSP &object_sp)=0
	Handle the arrival of asynchronous structured data from the process.

virtual Status	GetDescription (const StructuredData::ObjectSP &object_sp, lldb_private::Stream &stream)=0
	Get a human-readable description of the contents of the data.

virtual bool	GetEnabled (llvm::StringRef type_name) const
	Returns whether the plugin's features are enabled.

virtual void	ModulesDidLoad (Process &process, ModuleList &module_list)
	Allow the plugin to do work related to modules that loaded in the the corresponding 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

Protected Member Functions
	StructuredDataPlugin (const lldb::ProcessWP &process_wp)

Static Protected Member Functions
static void	InitializeBasePluginForDebugger (Debugger &debugger)
	Derived classes must call this before attempting to hook up commands to the 'plugin structured-data' tree.

Private Member Functions
	StructuredDataPlugin (const StructuredDataPlugin &)=delete

const StructuredDataPlugin &	operator= (const StructuredDataPlugin &)=delete

Private Attributes
lldb::ProcessWP	m_process_wp

Detailed Description

Plugin that supports process-related structured data sent asynchronously from the debug monitor (e.g.

debugserver, lldb-server, etc.)

This plugin type is activated by a Process-derived instance when that instance detects that a given structured data feature is available.

StructuredDataPlugin instances are inherently tied to a process. The main functionality they support is the ability to consume asynchronously- delivered structured data from the process monitor, and do something reasonable with it. Something reasonable can include broadcasting a StructuredData event, which other parts of the system can then do with as they please. An IDE could use this facility to retrieve CPU usage, memory usage, and other run-time aspects of the process. That data can then be displayed meaningfully to the user through the IDE. For command-line LLDB, the Debugger instance listens for the structured data events raised by the plugin, and give the plugin both the output and error streams such that the plugin can display something about the event, at a time when the debugger ensures it is safe to write to the output or error streams.

Definition at line 40 of file StructuredDataPlugin.h.

Constructor & Destructor Documentation

◆ ~StructuredDataPlugin()

StructuredDataPlugin::~StructuredDataPlugin ( )

overridedefault

◆ StructuredDataPlugin() [1/2]

StructuredDataPlugin::StructuredDataPlugin ( const lldb::ProcessWP & process_wp )

protected

Definition at line 30 of file StructuredDataPlugin.cpp.

◆ StructuredDataPlugin() [2/2]

lldb_private::StructuredDataPlugin::StructuredDataPlugin ( const StructuredDataPlugin & )

privatedelete

Member Function Documentation

◆ GetDescription()

virtual Status lldb_private::StructuredDataPlugin::GetDescription	(	const StructuredData::ObjectSP &	object_sp,
		lldb_private::Stream &	stream
	)

pure virtual

Get a human-readable description of the contents of the data.

In command-line LLDB, this method will be called by the Debugger instance for each structured data event generated, and the output will be printed to the LLDB console. If nothing is added to the stream, nothing will be printed; otherwise, a newline will be added to the end when displayed.

Parameters

[in]	object_sp	A shared pointer to the structured data to format.
[in]	stream	The stream where the structured data should be pretty printed.

Returns: The error if formatting the object contents failed; otherwise, success.

Implemented in lldb_private::StructuredDataDarwinLog.

◆ GetEnabled()

bool StructuredDataPlugin::GetEnabled ( llvm::StringRef type_name ) const

virtual

Returns whether the plugin's features are enabled.

This is a convenience method for plugins that can enable or disable their functionality. It allows retrieval of this state without requiring a cast.

Parameters

[in] type_name The name of the feature tag for the asynchronous structured data. This is needed for plugins that support more than one feature.

Reimplemented in lldb_private::StructuredDataDarwinLog.

Definition at line 35 of file StructuredDataPlugin.cpp.

◆ GetProcess()

ProcessSP StructuredDataPlugin::GetProcess ( ) const

Definition at line 41 of file StructuredDataPlugin.cpp.

References m_process_wp.

Referenced by lldb_private::StructuredDataDarwinLog::DumpHeader(), lldb_private::StructuredDataDarwinLog::EnableNow(), and lldb_private::StructuredDataDarwinLog::~StructuredDataDarwinLog().

◆ HandleArrivalOfStructuredData()

virtual void lldb_private::StructuredDataPlugin::HandleArrivalOfStructuredData	(	Process &	process,
		llvm::StringRef	type_name,
		const StructuredData::ObjectSP &	object_sp
	)

pure virtual

Handle the arrival of asynchronous structured data from the process.

When asynchronous structured data arrives from the process monitor, it is immediately delivered to the plugin mapped for that feature if one exists. The structured data that arrives from a process monitor must be a dictionary, and it must have a string field named "type" that must contain the StructuredData feature name set as the value. This is the manner in which the data is routed to the proper plugin instance.

Parameters

[in]	process	The process instance that just received the structured data. This will always be the same process for a given instance of a plugin.
[in]	type_name	The name of the feature tag for the asynchronous structured data. Note this data will also be present in the object_sp dictionary under the string value with key "type".
[in]	object_sp	A shared pointer to the structured data that arrived. This must be a dictionary. The only key required is the aforementioned key named "type" that must be a string value containing the structured data type name.

Implemented in lldb_private::StructuredDataDarwinLog.

◆ InitializeBasePluginForDebugger()

void StructuredDataPlugin::InitializeBasePluginForDebugger ( Debugger & debugger )

staticprotected

Derived classes must call this before attempting to hook up commands to the 'plugin structured-data' tree.

This ensures the relevant command and options hook points for all StructuredDataPlugin derived classes are available for this debugger. If this has already happened, this call is a no-op.

Parameters

[in] debugger The Debugger instance for which we're creating the required shared components for the StructuredDataPlugin derived classes.

Definition at line 45 of file StructuredDataPlugin.cpp.

References lldb_private::Debugger::GetCommandInterpreter(), and lldb_private::CommandInterpreter::GetCommandObject().

Referenced by lldb_private::StructuredDataDarwinLog::DebuggerInitialize().

◆ ModulesDidLoad()

void StructuredDataPlugin::ModulesDidLoad	(	Process &	process,
		ModuleList &	module_list
	)

virtual

Allow the plugin to do work related to modules that loaded in the the corresponding process.

This method defaults to doing nothing. Plugins can override it if they have any behavior they want to enable/modify based on loaded modules.

Parameters

[in]	process	The process that just was notified of modules having been loaded. This will always be the same process for a given instance of a plugin.
[in]	module_list	The list of modules that the process registered as having just loaded. See Process::ModulesDidLoad(...).

Reimplemented in lldb_private::StructuredDataDarwinLog.

Definition at line 64 of file StructuredDataPlugin.cpp.

◆ operator=()

const StructuredDataPlugin & lldb_private::StructuredDataPlugin::operator= ( const StructuredDataPlugin & )

privatedelete

◆ SupportsStructuredDataType()

virtual bool lldb_private::StructuredDataPlugin::SupportsStructuredDataType ( llvm::StringRef type_name )

pure virtual

Return whether this plugin supports the given StructuredData feature.

When Process is informed of a list of process-monitor-supported structured data features, Process will go through the list of plugins, one at a time, and have the first plugin that supports a given feature be the plugin instantiated to handle that feature. There is a 1-1 correspondence between a Process instance and a StructuredDataPlugin mapped to that process. A plugin can support handling multiple features, and if that happens, there is a single plugin instance created covering all of the mapped features for a given process.

Parameters

[in] type_name The name of the feature tag supported by a process. e.g. "darwin-log".

Returns: true if the plugin supports the feature; otherwise, false.

Implemented in lldb_private::StructuredDataDarwinLog.

Member Data Documentation

◆ m_process_wp

lldb::ProcessWP lldb_private::StructuredDataPlugin::m_process_wp

private

Definition at line 163 of file StructuredDataPlugin.h.

Referenced by GetProcess().

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

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~StructuredDataPlugin()

◆ StructuredDataPlugin() [1/2]

◆ StructuredDataPlugin() [2/2]

Member Function Documentation

◆ GetDescription()

◆ GetEnabled()

◆ GetProcess()

◆ HandleArrivalOfStructuredData()

◆ InitializeBasePluginForDebugger()

◆ ModulesDidLoad()

◆ operator=()

◆ SupportsStructuredDataType()

Member Data Documentation

◆ m_process_wp