StructuredDataPlugin.h revision 311128
1151497Sru//===-- StructuredDataPlugin.h ----------------------------------*- C++ -*-===// 2104862Sru// 3104862Sru// The LLVM Compiler Infrastructure 4104862Sru// 5104862Sru// This file is distributed under the University of Illinois Open Source 6104862Sru// License. See LICENSE.TXT for details. 7104862Sru// 8104862Sru//===----------------------------------------------------------------------===// 9104862Sru 10104862Sru#ifndef StructuredDataPlugin_h 11104862Sru#define StructuredDataPlugin_h 12104862Sru 13104862Sru#include "lldb/Core/PluginInterface.h" 14151497Sru#include "lldb/Core/StructuredData.h" 15104862Sru 16104862Srunamespace lldb_private { 17104862Sru 18104862Sruclass CommandObjectMultiword; 19104862Sru 20104862Sru// ----------------------------------------------------------------------------- 21104862Sru/// Plugin that supports process-related structured data sent asynchronously 22104862Sru/// from the debug monitor (e.g. debugserver, lldb-server, etc.) 23104862Sru/// 24104862Sru/// This plugin type is activated by a Process-derived instance when that 25104862Sru/// instance detects that a given structured data feature is available. 26104862Sru/// 27104862Sru/// StructuredDataPlugin instances are inherently tied to a process. The 28104862Sru/// main functionality they support is the ability to consume asynchronously- 29104862Sru/// delivered structured data from the process monitor, and do something 30104862Sru/// reasonable with it. Something reasonable can include broadcasting a 31104862Sru/// StructuredData event, which other parts of the system can then do with 32104862Sru/// as they please. An IDE could use this facility to retrieve CPU usage, 33151497Sru/// memory usage, and other run-time aspects of the process. That data 34104862Sru/// can then be displayed meaningfully to the user through the IDE. 35104862Sru 36104862Sru/// For command-line LLDB, the Debugger instance listens for the structured 37104862Sru/// data events raised by the plugin, and give the plugin both the output 38104862Sru/// and error streams such that the plugin can display something about the 39104862Sru/// event, at a time when the debugger ensures it is safe to write to the 40104862Sru/// output or error streams. 41104862Sru// ----------------------------------------------------------------------------- 42104862Sru 43104862Sruclass StructuredDataPlugin 44104862Sru : public PluginInterface, 45104862Sru public std::enable_shared_from_this<StructuredDataPlugin> { 46104862Srupublic: 47104862Sru virtual ~StructuredDataPlugin(); 48104862Sru 49104862Sru lldb::ProcessSP GetProcess() const; 50104862Sru 51104862Sru // ------------------------------------------------------------------------- 52104862Sru // Public instance API 53104862Sru // ------------------------------------------------------------------------- 54104862Sru 55104862Sru // ------------------------------------------------------------------------- 56104862Sru /// Return whether this plugin supports the given StructuredData feature. 57104862Sru /// 58104862Sru /// When Process is informed of a list of process-monitor-supported 59104862Sru /// structured data features, Process will go through the list of plugins, 60104862Sru /// one at a time, and have the first plugin that supports a given feature 61104862Sru /// be the plugin instantiated to handle that feature. There is a 1-1 62104862Sru /// correspondence between a Process instance and a StructuredDataPlugin 63104862Sru /// mapped to that process. A plugin can support handling multiple 64104862Sru /// features, and if that happens, there is a single plugin instance 65104862Sru /// created covering all of the mapped features for a given process. 66104862Sru /// 67104862Sru /// @param[in] type_name 68104862Sru /// The name of the feature tag supported by a process. 69104862Sru /// e.g. "darwin-log". 70104862Sru /// 71104862Sru /// @return 72104862Sru /// true if the plugin supports the feature; otherwise, false. 73104862Sru // ------------------------------------------------------------------------- 74104862Sru virtual bool SupportsStructuredDataType(const ConstString &type_name) = 0; 75104862Sru 76104862Sru // ------------------------------------------------------------------------- 77104862Sru /// Handle the arrival of asynchronous structured data from the process. 78104862Sru /// 79104862Sru /// When asynchronous structured data arrives from the process monitor, 80104862Sru /// it is immediately delivered to the plugin mapped for that feature 81104862Sru /// if one exists. The structured data that arrives from a process 82104862Sru /// monitor must be a dictionary, and it must have a string field named 83104862Sru /// "type" that must contain the StructuredData feature name set as the 84104862Sru /// value. This is the manner in which the data is routed to the proper 85104862Sru /// plugin instance. 86104862Sru /// 87151497Sru /// @param[in] process 88104862Sru /// The process instance that just received the structured data. 89104862Sru /// This will always be the same process for a given instance of 90104862Sru /// a plugin. 91104862Sru /// 92104862Sru /// @param[in] type_name 93104862Sru /// The name of the feature tag for the asynchronous structured data. 94104862Sru /// Note this data will also be present in the \b object_sp dictionary 95104862Sru /// under the string value with key "type". 96104862Sru /// 97104862Sru /// @param[in] object_sp 98104862Sru /// A shared pointer to the structured data that arrived. This must 99104862Sru /// be a dictionary. The only key required is the aforementioned 100104862Sru /// key named "type" that must be a string value containing the 101104862Sru /// structured data type name. 102104862Sru // ------------------------------------------------------------------------- 103104862Sru virtual void 104104862Sru HandleArrivalOfStructuredData(Process &process, const ConstString &type_name, 105104862Sru const StructuredData::ObjectSP &object_sp) = 0; 106104862Sru 107104862Sru // ------------------------------------------------------------------------- 108104862Sru /// Get a human-readable description of the contents of the data. 109104862Sru /// 110104862Sru /// In command-line LLDB, this method will be called by the Debugger 111104862Sru /// instance for each structured data event generated, and the output 112104862Sru /// will be printed to the LLDB console. If nothing is added to the stream, 113151497Sru /// nothing will be printed; otherwise, a newline will be added to the end 114151497Sru /// when displayed. 115104862Sru /// 116104862Sru /// @param[in] object_sp 117104862Sru /// A shared pointer to the structured data to format. 118151497Sru /// 119104862Sru /// @param[in] stream 120104862Sru /// The stream where the structured data should be pretty printed. 121104862Sru /// 122104862Sru /// @return 123104862Sru /// The error if formatting the object contents failed; otherwise, 124104862Sru /// success. 125104862Sru // ------------------------------------------------------------------------- 126104862Sru virtual Error GetDescription(const StructuredData::ObjectSP &object_sp, 127104862Sru lldb_private::Stream &stream) = 0; 128104862Sru 129104862Sru // ------------------------------------------------------------------------- 130104862Sru /// Returns whether the plugin's features are enabled. 131104862Sru /// 132104862Sru /// This is a convenience method for plugins that can enable or disable 133104862Sru /// their functionality. It allows retrieval of this state without 134104862Sru /// requiring a cast. 135104862Sru /// 136104862Sru /// @param[in] type_name 137104862Sru /// The name of the feature tag for the asynchronous structured data. 138104862Sru /// This is needed for plugins that support more than one feature. 139104862Sru // ------------------------------------------------------------------------- 140104862Sru virtual bool GetEnabled(const ConstString &type_name) const; 141104862Sru 142104862Sru // ------------------------------------------------------------------------- 143151497Sru /// Allow the plugin to do work related to modules that loaded in the 144104862Sru /// the corresponding process. 145104862Sru /// 146104862Sru /// This method defaults to doing nothing. Plugins can override it 147104862Sru /// if they have any behavior they want to enable/modify based on loaded 148104862Sru /// modules. 149104862Sru /// 150104862Sru /// @param[in] process 151104862Sru /// The process that just was notified of modules having been loaded. 152104862Sru /// This will always be the same process for a given instance of 153104862Sru /// a plugin. 154104862Sru /// 155104862Sru /// @param[in] module_list 156104862Sru /// The list of modules that the process registered as having just 157104862Sru /// loaded. See \b Process::ModulesDidLoad(...). 158104862Sru // ------------------------------------------------------------------------- 159104862Sru virtual void ModulesDidLoad(Process &process, ModuleList &module_list); 160151497Sru 161104862Sruprotected: 162104862Sru // ------------------------------------------------------------------------- 163104862Sru // Derived-class API 164104862Sru // ------------------------------------------------------------------------- 165104862Sru StructuredDataPlugin(const lldb::ProcessWP &process_wp); 166104862Sru 167151497Sru // ------------------------------------------------------------------------- 168104862Sru /// Derived classes must call this before attempting to hook up commands 169104862Sru /// to the 'plugin structured-data' tree. 170104862Sru /// 171104862Sru /// This ensures the relevant command and options hook points for all 172104862Sru /// StructuredDataPlugin derived classes are available for this debugger. 173104862Sru /// If this has already happened, this call is a no-op. 174104862Sru /// 175104862Sru /// @param[in] debugger 176104862Sru /// The Debugger instance for which we're creating the required shared 177104862Sru /// components for the StructuredDataPlugin derived classes. 178104862Sru // ------------------------------------------------------------------------- 179104862Sru static void InitializeBasePluginForDebugger(Debugger &debugger); 180104862Sru 181104862Sruprivate: 182104862Sru lldb::ProcessWP m_process_wp; 183104862Sru 184104862Sru DISALLOW_COPY_AND_ASSIGN(StructuredDataPlugin); 185104862Sru}; 186151497Sru} 187104862Sru 188104862Sru#endif 189104862Sru