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

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:
Inheritance graph
[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
 
PluginInterfaceoperator= (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 StructuredDataPluginoperator= (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_spA shared pointer to the structured data to format.
[in]streamThe 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_nameThe 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

◆ 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]processThe process instance that just received the structured data. This will always be the same process for a given instance of a plugin.
[in]type_nameThe 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_spA 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]debuggerThe 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]processThe 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_listThe 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_nameThe 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: