StructuredDataPlugin.h revision 311145
1//===-- StructuredDataPlugin.h ----------------------------------*- C++ -*-===// 2// 3// The LLVM Compiler Infrastructure 4// 5// This file is distributed under the University of Illinois Open Source 6// License. See LICENSE.TXT for details. 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef StructuredDataPlugin_h 11#define StructuredDataPlugin_h 12 13#include "lldb/Core/PluginInterface.h" 14#include "lldb/Core/StructuredData.h" 15 16namespace lldb_private { 17 18class CommandObjectMultiword; 19 20// ----------------------------------------------------------------------------- 21/// Plugin that supports process-related structured data sent asynchronously 22/// from the debug monitor (e.g. debugserver, lldb-server, etc.) 23/// 24/// This plugin type is activated by a Process-derived instance when that 25/// instance detects that a given structured data feature is available. 26/// 27/// StructuredDataPlugin instances are inherently tied to a process. The 28/// main functionality they support is the ability to consume asynchronously- 29/// delivered structured data from the process monitor, and do something 30/// reasonable with it. Something reasonable can include broadcasting a 31/// StructuredData event, which other parts of the system can then do with 32/// as they please. An IDE could use this facility to retrieve CPU usage, 33/// memory usage, and other run-time aspects of the process. That data 34/// can then be displayed meaningfully to the user through the IDE. 35 36/// For command-line LLDB, the Debugger instance listens for the structured 37/// data events raised by the plugin, and give the plugin both the output 38/// and error streams such that the plugin can display something about the 39/// event, at a time when the debugger ensures it is safe to write to the 40/// output or error streams. 41// ----------------------------------------------------------------------------- 42 43class StructuredDataPlugin 44 : public PluginInterface, 45 public std::enable_shared_from_this<StructuredDataPlugin> { 46public: 47 virtual ~StructuredDataPlugin(); 48 49 lldb::ProcessSP GetProcess() const; 50 51 // ------------------------------------------------------------------------- 52 // Public instance API 53 // ------------------------------------------------------------------------- 54 55 // ------------------------------------------------------------------------- 56 /// Return whether this plugin supports the given StructuredData feature. 57 /// 58 /// When Process is informed of a list of process-monitor-supported 59 /// structured data features, Process will go through the list of plugins, 60 /// one at a time, and have the first plugin that supports a given feature 61 /// be the plugin instantiated to handle that feature. There is a 1-1 62 /// correspondence between a Process instance and a StructuredDataPlugin 63 /// mapped to that process. A plugin can support handling multiple 64 /// features, and if that happens, there is a single plugin instance 65 /// created covering all of the mapped features for a given process. 66 /// 67 /// @param[in] type_name 68 /// The name of the feature tag supported by a process. 69 /// e.g. "darwin-log". 70 /// 71 /// @return 72 /// true if the plugin supports the feature; otherwise, false. 73 // ------------------------------------------------------------------------- 74 virtual bool SupportsStructuredDataType(const ConstString &type_name) = 0; 75 76 // ------------------------------------------------------------------------- 77 /// Handle the arrival of asynchronous structured data from the process. 78 /// 79 /// When asynchronous structured data arrives from the process monitor, 80 /// it is immediately delivered to the plugin mapped for that feature 81 /// if one exists. The structured data that arrives from a process 82 /// monitor must be a dictionary, and it must have a string field named 83 /// "type" that must contain the StructuredData feature name set as the 84 /// value. This is the manner in which the data is routed to the proper 85 /// plugin instance. 86 /// 87 /// @param[in] process 88 /// The process instance that just received the structured data. 89 /// This will always be the same process for a given instance of 90 /// a plugin. 91 /// 92 /// @param[in] type_name 93 /// The name of the feature tag for the asynchronous structured data. 94 /// Note this data will also be present in the \b object_sp dictionary 95 /// under the string value with key "type". 96 /// 97 /// @param[in] object_sp 98 /// A shared pointer to the structured data that arrived. This must 99 /// be a dictionary. The only key required is the aforementioned 100 /// key named "type" that must be a string value containing the 101 /// structured data type name. 102 // ------------------------------------------------------------------------- 103 virtual void 104 HandleArrivalOfStructuredData(Process &process, const ConstString &type_name, 105 const StructuredData::ObjectSP &object_sp) = 0; 106 107 // ------------------------------------------------------------------------- 108 /// Get a human-readable description of the contents of the data. 109 /// 110 /// In command-line LLDB, this method will be called by the Debugger 111 /// instance for each structured data event generated, and the output 112 /// will be printed to the LLDB console. If nothing is added to the stream, 113 /// nothing will be printed; otherwise, a newline will be added to the end 114 /// when displayed. 115 /// 116 /// @param[in] object_sp 117 /// A shared pointer to the structured data to format. 118 /// 119 /// @param[in] stream 120 /// The stream where the structured data should be pretty printed. 121 /// 122 /// @return 123 /// The error if formatting the object contents failed; otherwise, 124 /// success. 125 // ------------------------------------------------------------------------- 126 virtual Error GetDescription(const StructuredData::ObjectSP &object_sp, 127 lldb_private::Stream &stream) = 0; 128 129 // ------------------------------------------------------------------------- 130 /// Returns whether the plugin's features are enabled. 131 /// 132 /// This is a convenience method for plugins that can enable or disable 133 /// their functionality. It allows retrieval of this state without 134 /// requiring a cast. 135 /// 136 /// @param[in] type_name 137 /// The name of the feature tag for the asynchronous structured data. 138 /// This is needed for plugins that support more than one feature. 139 // ------------------------------------------------------------------------- 140 virtual bool GetEnabled(const ConstString &type_name) const; 141 142 // ------------------------------------------------------------------------- 143 /// Allow the plugin to do work related to modules that loaded in the 144 /// the corresponding process. 145 /// 146 /// This method defaults to doing nothing. Plugins can override it 147 /// if they have any behavior they want to enable/modify based on loaded 148 /// modules. 149 /// 150 /// @param[in] process 151 /// The process that just was notified of modules having been loaded. 152 /// This will always be the same process for a given instance of 153 /// a plugin. 154 /// 155 /// @param[in] module_list 156 /// The list of modules that the process registered as having just 157 /// loaded. See \b Process::ModulesDidLoad(...). 158 // ------------------------------------------------------------------------- 159 virtual void ModulesDidLoad(Process &process, ModuleList &module_list); 160 161protected: 162 // ------------------------------------------------------------------------- 163 // Derived-class API 164 // ------------------------------------------------------------------------- 165 StructuredDataPlugin(const lldb::ProcessWP &process_wp); 166 167 // ------------------------------------------------------------------------- 168 /// Derived classes must call this before attempting to hook up commands 169 /// to the 'plugin structured-data' tree. 170 /// 171 /// This ensures the relevant command and options hook points for all 172 /// StructuredDataPlugin derived classes are available for this debugger. 173 /// If this has already happened, this call is a no-op. 174 /// 175 /// @param[in] debugger 176 /// The Debugger instance for which we're creating the required shared 177 /// components for the StructuredDataPlugin derived classes. 178 // ------------------------------------------------------------------------- 179 static void InitializeBasePluginForDebugger(Debugger &debugger); 180 181private: 182 lldb::ProcessWP m_process_wp; 183 184 DISALLOW_COPY_AND_ASSIGN(StructuredDataPlugin); 185}; 186} 187 188#endif 189