LLDB  mainline
TargetList.h
Go to the documentation of this file.
1 //===-- TargetList.h --------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef liblldb_TargetList_h_
10 #define liblldb_TargetList_h_
11 
12 #include <mutex>
13 #include <vector>
14 
15 #include "lldb/Target/Target.h"
17 
18 namespace lldb_private {
19 
20 class TargetList : public Broadcaster {
21 private:
22  friend class Debugger;
23 
24  /// Constructor
25  ///
26  /// The constructor for the target list is private. Clients can
27  /// get ahold of of the one and only target list through the
28  /// lldb_private::Debugger::GetSharedInstance().GetTargetList().
29  ///
30  /// \see static TargetList& lldb_private::Debugger::GetTargetList().
31  TargetList(Debugger &debugger);
32 
33 public:
34  /// Broadcaster event bits definitions.
35  enum { eBroadcastBitInterrupt = (1 << 0) };
36 
37  // These two functions fill out the Broadcaster interface:
38 
40 
41  ConstString &GetBroadcasterClass() const override {
43  }
44 
45  ~TargetList() override;
46 
47  /// Create a new Target.
48  ///
49  /// Clients must use this function to create a Target. This allows
50  /// a global list of targets to be maintained in a central location
51  /// so signal handlers and other global functions can use it to
52  /// locate an appropriate target to deliver asynchronous information
53  /// to.
54  ///
55  /// \param[in] debugger
56  /// The debugger to associate this target with
57  ///
58  /// \param[in] file_spec
59  /// The main executable file for a debug target. This value
60  /// can be nullptr and the file can be set later using:
61  /// Target::SetExecutableModule (ModuleSP&)
62  ///
63  /// \param[in] triple_cstr
64  /// A target triple string to be used for the target. This can
65  /// be nullptr if the triple is not known or when attaching to a
66  /// process.
67  ///
68  /// \param[in] get_dependent_modules
69  /// Track down the dependent modules for an executable and
70  /// load those into the module list.
71  ///
72  /// \param[in] platform_options
73  /// A pointer to the platform options to use when creating this
74  /// target. If this value is nullptr, then the currently selected
75  /// platform will be used.
76  ///
77  /// \param[out] target_sp
78  /// A shared pointer to a target that will be filled in if
79  /// this call is successful.
80  ///
81  /// \return
82  /// An error object that indicates success or failure
83  Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path,
84  llvm::StringRef triple_str,
85  LoadDependentFiles get_dependent_modules,
86  const OptionGroupPlatform *platform_options,
87  lldb::TargetSP &target_sp);
88 
89  /// Create a new Target.
90  ///
91  /// Same as the function above, but used when you already know the
92  /// platform you will be using
93  Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path,
94  const ArchSpec &arch,
95  LoadDependentFiles get_dependent_modules,
96  lldb::PlatformSP &platform_sp, lldb::TargetSP &target_sp);
97 
98  /// Delete a Target object from the list.
99  ///
100  /// When clients are done with the Target objects, this function
101  /// should be called to release the memory associated with a target
102  /// object.
103  ///
104  /// \param[in] target_sp
105  /// The shared pointer to a target.
106  ///
107  /// \return
108  /// Returns \b true if the target was successfully removed from
109  /// from this target list, \b false otherwise. The client will
110  /// be left with the last remaining shared pointer to the target
111  /// in \a target_sp which can then be properly released.
112  bool DeleteTarget(lldb::TargetSP &target_sp);
113 
114  int GetNumTargets() const;
115 
116  lldb::TargetSP GetTargetAtIndex(uint32_t index) const;
117 
118  uint32_t GetIndexOfTarget(lldb::TargetSP target_sp) const;
119 
120  /// Find the target that contains has an executable whose path
121  /// matches \a exe_file_spec, and whose architecture matches
122  /// \a arch_ptr if arch_ptr is not nullptr.
123  ///
124  /// \param[in] exe_file_spec
125  /// A file spec containing a basename, or a full path (directory
126  /// and basename). If \a exe_file_spec contains only a filename
127  /// (empty GetDirectory() value) then matching will be done
128  /// solely based on the filenames and directories won't be
129  /// compared. If \a exe_file_spec contains a filename and a
130  /// directory, then both must match.
131  ///
132  /// \param[in] exe_arch_ptr
133  /// If not nullptr then the architecture also needs to match, else
134  /// the architectures will be compared.
135  ///
136  /// \return
137  /// A shared pointer to a target object. The returned shared
138  /// pointer will contain nullptr if no target objects have a
139  /// executable whose full or partial path matches
140  /// with a matching process ID.
142  const FileSpec &exe_file_spec,
143  const ArchSpec *exe_arch_ptr = nullptr) const;
144 
145  /// Find the target that contains a process with process ID \a
146  /// pid.
147  ///
148  /// \param[in] pid
149  /// The process ID to search our target list for.
150  ///
151  /// \return
152  /// A shared pointer to a target object. The returned shared
153  /// pointer will contain nullptr if no target objects own a process
154  /// with a matching process ID.
155  lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid) const;
156 
157  lldb::TargetSP FindTargetWithProcess(lldb_private::Process *process) const;
158 
159  lldb::TargetSP GetTargetSP(Target *target) const;
160 
161  /// Send an async interrupt to one or all processes.
162  ///
163  /// Find the target that contains the process with process ID \a
164  /// pid and send a LLDB_EVENT_ASYNC_INTERRUPT event to the process's
165  /// event queue.
166  ///
167  /// \param[in] pid
168  /// The process ID to search our target list for, if \a pid is
169  /// LLDB_INVALID_PROCESS_ID, then the interrupt will be sent to
170  /// all processes.
171  ///
172  /// \return
173  /// The number of async interrupts sent.
175 
176  uint32_t SignalIfRunning(lldb::pid_t pid, int signo);
177 
179 
180  lldb::TargetSP GetSelectedTarget();
181 
182 protected:
183  typedef std::vector<lldb::TargetSP> collection;
184  // Member variables.
185  collection m_target_list;
186  lldb::TargetSP m_dummy_target_sp;
187  mutable std::recursive_mutex m_target_list_mutex;
189 
190 private:
191  lldb::TargetSP GetDummyTarget(lldb_private::Debugger &debugger);
192 
193  Status CreateDummyTarget(Debugger &debugger,
194  llvm::StringRef specified_arch_name,
195  lldb::TargetSP &target_sp);
196 
197  Status CreateTargetInternal(Debugger &debugger, llvm::StringRef user_exe_path,
198  llvm::StringRef triple_str,
199  LoadDependentFiles load_dependent_files,
200  const OptionGroupPlatform *platform_options,
201  lldb::TargetSP &target_sp, bool is_dummy_target);
202 
203  Status CreateTargetInternal(Debugger &debugger, llvm::StringRef user_exe_path,
204  const ArchSpec &arch,
205  LoadDependentFiles get_dependent_modules,
206  lldb::PlatformSP &platform_sp,
207  lldb::TargetSP &target_sp, bool is_dummy_target);
208 
209  DISALLOW_COPY_AND_ASSIGN(TargetList);
210 };
211 
212 } // namespace lldb_private
213 
214 #endif // liblldb_TargetList_h_
uint32_t GetIndexOfTarget(lldb::TargetSP target_sp) const
Definition: TargetList.cpp:591
lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid) const
Find the target that contains a process with process ID pid.
Definition: TargetList.cpp:481
A class to manage flag bits.
Definition: Debugger.h:82
std::recursive_mutex m_target_list_mutex
Definition: TargetList.h:187
lldb::TargetSP FindTargetWithExecutableAndArchitecture(const FileSpec &exe_file_spec, const ArchSpec *exe_arch_ptr=nullptr) const
Find the target that contains has an executable whose path matches exe_file_spec, and whose architect...
Definition: TargetList.cpp:456
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
#define LLDB_INVALID_PROCESS_ID
Definition: lldb-defines.h:92
uint32_t SignalIfRunning(lldb::pid_t pid, int signo)
Definition: TargetList.cpp:546
static ConstString & GetStaticBroadcasterClass()
Definition: TargetList.cpp:32
uint32_t SendAsyncInterrupt(lldb::pid_t pid=LLDB_INVALID_PROCESS_ID)
Send an async interrupt to one or all processes.
Definition: TargetList.cpp:525
A file utility class.
Definition: FileSpec.h:55
An architecture specification class.
Definition: ArchSpec.h:32
An event broadcasting class.
Definition: Broadcaster.h:250
ConstString & GetBroadcasterClass() const override
Definition: TargetList.h:41
LoadDependentFiles
Definition: Target.h:59
Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path, llvm::StringRef triple_str, LoadDependentFiles get_dependent_modules, const OptionGroupPlatform *platform_options, lldb::TargetSP &target_sp)
Create a new Target.
uint32_t m_selected_target_idx
Definition: TargetList.h:188
bool DeleteTarget(lldb::TargetSP &target_sp)
Delete a Target object from the list.
Definition: TargetList.cpp:443
std::vector< lldb::TargetSP > collection
Definition: TargetList.h:183
lldb::TargetSP GetTargetSP(Target *target) const
Definition: TargetList.cpp:510
lldb::TargetSP FindTargetWithProcess(lldb_private::Process *process) const
Definition: TargetList.cpp:495
A plug-in interface definition class for debugging a process.
Definition: Process.h:353
lldb::TargetSP GetTargetAtIndex(uint32_t index) const
Definition: TargetList.cpp:583
A uniqued constant string class.
Definition: ConstString.h:38
uint64_t pid_t
Definition: lldb-types.h:85
uint32_t SetSelectedTarget(Target *target)
Definition: TargetList.cpp:601
lldb::TargetSP GetSelectedTarget()
Definition: TargetList.cpp:615
lldb::TargetSP m_dummy_target_sp
Definition: TargetList.h:186
An error handling class.
Definition: Status.h:44