contrib/llvm/tools/lldb/include/lldb/Target/SystemRuntime.h

   1 //===-- SystemRuntime.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 liblldb_SystemRuntime_h_
  11 #define liblldb_SystemRuntime_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 // Other libraries and framework includes
  16 // Project includes
  17 #include <vector>
  18
  19 #include "lldb/lldb-public.h"
  20 #include "lldb/Core/ConstString.h"
  21 #include "lldb/Core/ModuleList.h"
  22 #include "lldb/Core/PluginInterface.h"
  23 #include "lldb/lldb-private.h"
  24
  25
  26 namespace lldb_private {
  27
  28 //----------------------------------------------------------------------
  29 /// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h"
  30 /// @brief A plug-in interface definition class for system runtimes.
  31 ///
  32 /// The system runtime plugins can collect information from the system
  33 /// libraries during a Process' lifetime and provide information about
  34 /// how objects/threads were originated.
  35 ///
  36 /// For instance, a system runtime plugin use a breakpoint when threads
  37 /// are created to record the backtrace of where that thread was created.
  38 /// Later, when backtracing the created thread, it could extend the backtrace
  39 /// to show where it was originally created from.
  40 ///
  41 /// The plugin will insert its own breakpoint when Created and start collecting
  42 /// information.  Later when it comes time to augment a Thread, it can be
  43 /// asked to provide that information.
  44 ///
  45 //----------------------------------------------------------------------
  46
  47 class SystemRuntime :
  48     public PluginInterface
  49 {
  50 public:
  51     //------------------------------------------------------------------
  52     /// Find a system runtime plugin for a given process.
  53     ///
  54     /// Scans the installed SystemRuntime plugins and tries to find
  55     /// an instance that can be used to track image changes in \a
  56     /// process.
  57     ///
  58     /// @param[in] process
  59     ///     The process for which to try and locate a system runtime
  60     ///     plugin instance.
  61     //------------------------------------------------------------------
  62     static SystemRuntime*
  63     FindPlugin (Process *process);
  64
  65     //------------------------------------------------------------------
  66     /// Construct with a process.
  67     // -----------------------------------------------------------------
  68     SystemRuntime(lldb_private::Process *process);
  69
  70     //------------------------------------------------------------------
  71     /// Destructor.
  72     ///
  73     /// The destructor is virtual since this class is designed to be
  74     /// inherited by the plug-in instance.
  75     //------------------------------------------------------------------
  76     virtual
  77     ~SystemRuntime();
  78
  79     //------------------------------------------------------------------
  80     /// Called after attaching to a process.
  81     ///
  82     /// Allow the SystemRuntime plugin to execute some code after attaching
  83     /// to a process.
  84     //------------------------------------------------------------------
  85     virtual void
  86     DidAttach ();
  87
  88     //------------------------------------------------------------------
  89     /// Called after launching a process.
  90     ///
  91     /// Allow the SystemRuntime plugin to execute some code after launching
  92     /// a process.
  93     //------------------------------------------------------------------
  94     virtual void
  95     DidLaunch();
  96
  97     //------------------------------------------------------------------
  98     /// Called when modules have been loaded in the process.
  99     ///
 100     /// Allow the SystemRuntime plugin to enable logging features in the
 101     /// system runtime libraries.
 102     //------------------------------------------------------------------
 103     virtual void
 104     ModulesDidLoad(lldb_private::ModuleList &module_list);
 105
 106
 107     //------------------------------------------------------------------
 108     /// Return a list of thread origin extended backtraces that may
 109     /// be available.
 110     ///
 111     /// A System Runtime may be able to provide a backtrace of when this
 112     /// thread was originally created.  Furthermore, it may be able to
 113     /// provide that extended backtrace for different styles of creation.
 114     /// On a system with both pthreads and libdispatch, aka Grand Central
 115     /// Dispatch, queues, the system runtime may be able to provide the
 116     /// pthread creation of the thread and it may also be able to provide
 117     /// the backtrace of when this GCD queue work block was enqueued.
 118     /// The caller may request these different origins by name.
 119     ///
 120     /// The names will be provided in the order that they are most likely
 121     /// to be requested.  For instance, a most natural order may be to
 122     /// request the GCD libdispatch queue origin.  If there is none, then
 123     /// request the pthread origin.
 124     ///
 125     /// @return
 126     ///   A vector of ConstStrings with names like "pthread" or "libdispatch".
 127     ///   An empty vector may be returned if no thread origin extended
 128     ///   backtrace capabilities are available.
 129     //------------------------------------------------------------------
 130     virtual const std::vector<ConstString> &
 131     GetExtendedBacktraceTypes ();
 132
 133     //------------------------------------------------------------------
 134     /// Return a Thread which shows the origin of this thread's creation.
 135     ///
 136     /// This likely returns a HistoryThread which shows how thread was
 137     /// originally created (e.g. "pthread" type), or how the work that
 138     /// is currently executing on it was originally enqueued (e.g.
 139     /// "libdispatch" type).
 140     ///
 141     /// There may be a chain of thread-origins; it may be informative to
 142     /// the end user to query the returned ThreadSP for its origins as
 143     /// well.
 144     ///
 145     /// @param [in] thread
 146     ///   The thread to examine.
 147     ///
 148     /// @param [in] type
 149     ///   The type of thread origin being requested.  The types supported
 150     ///   are returned from SystemRuntime::GetExtendedBacktraceTypes.
 151     ///
 152     /// @return
 153     ///   A ThreadSP which will have a StackList of frames.  This Thread will
 154     ///   not appear in the Process' list of current threads.  Normal thread
 155     ///   operations like stepping will not be available.  This is a historical
 156     ///   view thread and may be only useful for showing a backtrace.
 157     ///
 158     ///   An empty ThreadSP will be returned if no thread origin is available.
 159     //------------------------------------------------------------------
 160     virtual lldb::ThreadSP
 161     GetExtendedBacktraceThread (lldb::ThreadSP thread, ConstString type);
 162
 163 protected:
 164     //------------------------------------------------------------------
 165     // Member variables.
 166     //------------------------------------------------------------------
 167     Process *m_process;
 168
 169     std::vector<ConstString> m_types;
 170
 171 private:
 172     DISALLOW_COPY_AND_ASSIGN (SystemRuntime);
 173 };
 174
 175 } // namespace lldb_private
 176
 177 #endif  // liblldb_SystemRuntime_h_