include/lldb/Target/StructuredDataPlugin.h

   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
  16 namespace lldb_private {
  17
  18 class 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
  43 class StructuredDataPlugin
  44     : public PluginInterface,
  45       public std::enable_shared_from_this<StructuredDataPlugin> {
  46 public:
  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
 161 protected:
 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
 181 private:
 182   lldb::ProcessWP m_process_wp;
 183
 184   DISALLOW_COPY_AND_ASSIGN(StructuredDataPlugin);
 185 };
 186 }
 187
 188 #endif