SystemRuntime.h revision 263367 
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 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
163protected:
164    //------------------------------------------------------------------
165    // Member variables.
166    //------------------------------------------------------------------
167    Process *m_process;
168
169    std::vector<ConstString> m_types;
170
171private:
172    DISALLOW_COPY_AND_ASSIGN (SystemRuntime);
173};
174
175} // namespace lldb_private
176
177#endif  // liblldb_SystemRuntime_h_
178