SystemRuntime.h revision 263363
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 26namespace 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 47class SystemRuntime : 48 public PluginInterface 49{ 50public: 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 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 GetExtendedBacktrace (lldb::ThreadSP thread, ConstString type); 162 163protected: 164 //------------------------------------------------------------------ 165 // Member variables. 166 //------------------------------------------------------------------ 167 Process *m_process; 168private: 169 DISALLOW_COPY_AND_ASSIGN (SystemRuntime); 170}; 171 172} // namespace lldb_private 173 174#endif // liblldb_SystemRuntime_h_ 175