1 //===-- ModuleList.h --------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_ModuleList_h_
10 #define liblldb_ModuleList_h_
12 #include "lldb/Core/Address.h"
13 #include "lldb/Core/ModuleSpec.h"
14 #include "lldb/Core/UserSettingsController.h"
15 #include "lldb/Utility/FileSpec.h"
16 #include "lldb/Utility/Iterable.h"
17 #include "lldb/Utility/Status.h"
18 #include "lldb/lldb-enumerations.h"
19 #include "lldb/lldb-forward.h"
20 #include "lldb/lldb-types.h"
22 #include "llvm/ADT/DenseSet.h"
32 namespace lldb_private {
38 class RegularExpression;
41 class SymbolContextList;
48 class ModuleListProperties : public Properties {
50 ModuleListProperties();
52 FileSpec GetClangModulesCachePath() const;
53 bool SetClangModulesCachePath(llvm::StringRef path);
54 bool GetEnableExternalLookup() const;
55 bool SetEnableExternalLookup(bool new_value);
58 /// \class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
59 /// A collection class for Module objects.
61 /// Modules in the module collection class are stored as reference counted
62 /// shared pointers to Module objects.
67 virtual ~Notifier() = default;
69 virtual void NotifyModuleAdded(const ModuleList &module_list,
70 const lldb::ModuleSP &module_sp) = 0;
71 virtual void NotifyModuleRemoved(const ModuleList &module_list,
72 const lldb::ModuleSP &module_sp) = 0;
73 virtual void NotifyModuleUpdated(const ModuleList &module_list,
74 const lldb::ModuleSP &old_module_sp,
75 const lldb::ModuleSP &new_module_sp) = 0;
76 virtual void NotifyWillClearList(const ModuleList &module_list) = 0;
78 virtual void NotifyModulesRemoved(lldb_private::ModuleList &module_list) = 0;
81 /// Default constructor.
83 /// Creates an empty list of Module objects.
88 /// Creates a new module list object with a copy of the modules from \a rhs.
91 /// Another module list object.
92 ModuleList(const ModuleList &rhs);
94 ModuleList(ModuleList::Notifier *notifier);
99 /// Assignment operator.
101 /// Copies the module list from \a rhs into this list.
104 /// Another module list object.
107 /// A const reference to this object.
108 const ModuleList &operator=(const ModuleList &rhs);
110 /// Append a module to the module list.
112 /// \param[in] module_sp
113 /// A shared pointer to a module to add to this collection.
115 /// \param[in] notify
116 /// If true, and a notifier function is set, the notifier function
117 /// will be called. Defaults to true.
119 /// When this ModuleList is the Target's ModuleList, the notifier
120 /// function is Target::ModulesDidLoad -- the call to
121 /// ModulesDidLoad may be deferred when adding multiple Modules
122 /// to the Target, but it must be called at the end,
123 /// before resuming execution.
124 void Append(const lldb::ModuleSP &module_sp, bool notify = true);
126 /// Append a module to the module list and remove any equivalent modules.
127 /// Equivalent modules are ones whose file, platform file and architecture
130 /// Replaces the module to the collection.
132 /// \param[in] module_sp
133 /// A shared pointer to a module to replace in this collection.
134 void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
136 /// Append a module to the module list, if it is not already there.
138 /// \param[in] notify
139 /// If true, and a notifier function is set, the notifier function
140 /// will be called. Defaults to true.
142 /// When this ModuleList is the Target's ModuleList, the notifier
143 /// function is Target::ModulesDidLoad -- the call to
144 /// ModulesDidLoad may be deferred when adding multiple Modules
145 /// to the Target, but it must be called at the end,
146 /// before resuming execution.
147 bool AppendIfNeeded(const lldb::ModuleSP &module_sp, bool notify = true);
149 void Append(const ModuleList &module_list);
151 bool AppendIfNeeded(const ModuleList &module_list);
153 bool ReplaceModule(const lldb::ModuleSP &old_module_sp,
154 const lldb::ModuleSP &new_module_sp);
156 /// Clear the object's state.
158 /// Clears the list of modules and releases a reference to each module
159 /// object and if the reference count goes to zero, the module will be
163 /// Clear the object's state.
165 /// Clears the list of modules and releases a reference to each module
166 /// object and if the reference count goes to zero, the module will be
167 /// deleted. Also release all memory that might be held by any collection
168 /// classes (like std::vector)
171 /// Dump the description of each module contained in this list.
173 /// Dump the description of each module contained in this list to the
174 /// supplied stream \a s.
177 /// The stream to which to dump the object description.
179 /// \see Module::Dump(Stream *) const
180 void Dump(Stream *s) const;
182 void LogUUIDAndPaths(Log *log, const char *prefix_cstr);
184 std::recursive_mutex &GetMutex() const { return m_modules_mutex; }
186 size_t GetIndexForModule(const Module *module) const;
188 /// Get the module shared pointer for the module at index \a idx.
191 /// An index into this module collection.
194 /// A shared pointer to a Module which can contain NULL if
195 /// \a idx is out of range.
197 /// \see ModuleList::GetSize()
198 lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
200 /// Get the module shared pointer for the module at index \a idx without
201 /// acquiring the ModuleList mutex. This MUST already have been acquired
202 /// with ModuleList::GetMutex and locked for this call to be safe.
205 /// An index into this module collection.
208 /// A shared pointer to a Module which can contain NULL if
209 /// \a idx is out of range.
211 /// \see ModuleList::GetSize()
212 lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
214 /// Get the module pointer for the module at index \a idx.
217 /// An index into this module collection.
220 /// A pointer to a Module which can by nullptr if \a idx is out
223 /// \see ModuleList::GetSize()
224 Module *GetModulePointerAtIndex(size_t idx) const;
226 /// Get the module pointer for the module at index \a idx without acquiring
227 /// the ModuleList mutex. This MUST already have been acquired with
228 /// ModuleList::GetMutex and locked for this call to be safe.
231 /// An index into this module collection.
234 /// A pointer to a Module which can by nullptr if \a idx is out
237 /// \see ModuleList::GetSize()
238 Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
240 /// Find compile units by partial or full path.
242 /// Finds all compile units that match \a path in all of the modules and
243 /// returns the results in \a sc_list.
246 /// The name of the compile unit we are looking for.
248 /// \param[out] sc_list
249 /// A symbol context list that gets filled in with all of the
251 void FindCompileUnits(const FileSpec &path, SymbolContextList &sc_list) const;
253 /// \see Module::FindFunctions ()
254 void FindFunctions(ConstString name, lldb::FunctionNameType name_type_mask,
255 bool include_symbols, bool include_inlines,
256 SymbolContextList &sc_list) const;
258 /// \see Module::FindFunctionSymbols ()
259 void FindFunctionSymbols(ConstString name,
260 lldb::FunctionNameType name_type_mask,
261 SymbolContextList &sc_list);
263 /// \see Module::FindFunctions ()
264 void FindFunctions(const RegularExpression &name, bool include_symbols,
265 bool include_inlines, SymbolContextList &sc_list);
267 /// Find global and static variables by name.
270 /// The name of the global or static variable we are looking
273 /// \param[in] max_matches
274 /// Allow the number of matches to be limited to \a
275 /// max_matches. Specify UINT32_MAX to get all possible matches.
277 /// \param[in] variable_list
278 /// A list of variables that gets the matches appended to.
279 void FindGlobalVariables(ConstString name, size_t max_matches,
280 VariableList &variable_list) const;
282 /// Find global and static variables by regular expression.
285 /// A regular expression to use when matching the name.
287 /// \param[in] max_matches
288 /// Allow the number of matches to be limited to \a
289 /// max_matches. Specify UINT32_MAX to get all possible matches.
291 /// \param[in] variable_list
292 /// A list of variables that gets the matches appended to.
293 void FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
294 VariableList &variable_list) const;
296 /// Finds the first module whose file specification matches \a file_spec.
298 /// \param[in] module_spec
299 /// A file specification object to match against the Module's
300 /// file specifications. If \a file_spec does not have
301 /// directory information, matches will occur by matching only
302 /// the basename of any modules in this list. If this value is
303 /// NULL, then file specifications won't be compared when
304 /// searching for matching modules.
306 /// \param[out] matching_module_list
307 /// A module list that gets filled in with any modules that
308 /// match the search criteria.
309 void FindModules(const ModuleSpec &module_spec,
310 ModuleList &matching_module_list) const;
312 lldb::ModuleSP FindModule(const Module *module_ptr) const;
314 // Find a module by UUID
316 // The UUID value for a module is extracted from the ObjectFile and is the
317 // MD5 checksum, or a smarter object file equivalent, so finding modules by
318 // UUID values is very efficient and accurate.
319 lldb::ModuleSP FindModule(const UUID &uuid) const;
321 lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
323 void FindSymbolsWithNameAndType(ConstString name,
324 lldb::SymbolType symbol_type,
325 SymbolContextList &sc_list) const;
327 void FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
328 lldb::SymbolType symbol_type,
329 SymbolContextList &sc_list) const;
331 /// Find types by name.
333 /// \param[in] search_first
334 /// If non-null, this module will be searched before any other
338 /// The name of the type we are looking for.
340 /// \param[in] max_matches
341 /// Allow the number of matches to be limited to \a
342 /// max_matches. Specify UINT32_MAX to get all possible matches.
344 /// \param[out] types
345 /// A type list gets populated with any matches.
347 void FindTypes(Module *search_first, ConstString name,
348 bool name_is_fully_qualified, size_t max_matches,
349 llvm::DenseSet<SymbolFile *> &searched_symbol_files,
350 TypeList &types) const;
352 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
354 /// Find addresses by file/line
356 /// \param[in] target_sp
357 /// The target the addresses are desired for.
360 /// Source file to locate.
363 /// Source line to locate.
365 /// \param[in] function
366 /// Optional filter function. Addresses within this function will be
367 /// added to the 'local' list. All others will be added to the 'extern'
370 /// \param[out] output_local
371 /// All matching addresses within 'function'
373 /// \param[out] output_extern
374 /// All matching addresses not within 'function'
375 void FindAddressesForLine(const lldb::TargetSP target_sp,
376 const FileSpec &file, uint32_t line,
378 std::vector<Address> &output_local,
379 std::vector<Address> &output_extern);
381 /// Remove a module from the module list.
383 /// \param[in] module_sp
384 /// A shared pointer to a module to remove from this collection.
386 /// \param[in] notify
387 /// If true, and a notifier function is set, the notifier function
388 /// will be called. Defaults to true.
390 /// When this ModuleList is the Target's ModuleList, the notifier
391 /// function is Target::ModulesDidUnload -- the call to
392 /// ModulesDidUnload may be deferred when removing multiple Modules
393 /// from the Target, but it must be called at the end,
394 /// before resuming execution.
395 bool Remove(const lldb::ModuleSP &module_sp, bool notify = true);
397 size_t Remove(ModuleList &module_list);
399 bool RemoveIfOrphaned(const Module *module_ptr);
401 size_t RemoveOrphans(bool mandatory);
403 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
405 /// \copydoc Module::ResolveSymbolContextForAddress (const Address
406 /// &,uint32_t,SymbolContext&)
407 uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
408 lldb::SymbolContextItem resolve_scope,
409 SymbolContext &sc) const;
411 /// \copydoc Module::ResolveSymbolContextForFilePath (const char
412 /// *,uint32_t,bool,uint32_t,SymbolContextList&)
413 uint32_t ResolveSymbolContextForFilePath(
414 const char *file_path, uint32_t line, bool check_inlines,
415 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
417 /// \copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
418 /// &,uint32_t,bool,uint32_t,SymbolContextList&)
419 uint32_t ResolveSymbolContextsForFileSpec(
420 const FileSpec &file_spec, uint32_t line, bool check_inlines,
421 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
423 /// Gets the size of the module list.
426 /// The number of modules in the module list.
427 size_t GetSize() const;
428 bool IsEmpty() const { return !GetSize(); }
430 bool LoadScriptingResourcesInTarget(Target *target, std::list<Status> &errors,
431 Stream *feedback_stream = nullptr,
432 bool continue_on_error = true);
434 static ModuleListProperties &GetGlobalModuleListProperties();
436 static bool ModuleIsInCache(const Module *module_ptr);
438 static Status GetSharedModule(const ModuleSpec &module_spec,
439 lldb::ModuleSP &module_sp,
440 const FileSpecList *module_search_paths_ptr,
441 lldb::ModuleSP *old_module_sp_ptr,
442 bool *did_create_ptr,
443 bool always_create = false);
445 static bool RemoveSharedModule(lldb::ModuleSP &module_sp);
447 static void FindSharedModules(const ModuleSpec &module_spec,
448 ModuleList &matching_module_list);
450 static size_t RemoveOrphanSharedModules(bool mandatory);
452 static bool RemoveSharedModuleIfOrphaned(const Module *module_ptr);
454 void ForEach(std::function<bool(const lldb::ModuleSP &module_sp)> const
459 typedef std::vector<lldb::ModuleSP>
460 collection; ///< The module collection type.
462 void AppendImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
464 bool RemoveImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
466 collection::iterator RemoveImpl(collection::iterator pos,
467 bool use_notifier = true);
469 void ClearImpl(bool use_notifier = true);
472 collection m_modules; ///< The collection of modules.
473 mutable std::recursive_mutex m_modules_mutex;
475 Notifier *m_notifier;
478 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter,
479 std::recursive_mutex>
481 ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); }
483 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter>
484 ModuleIterableNoLocking;
485 ModuleIterableNoLocking ModulesNoLocking() {
486 return ModuleIterableNoLocking(m_modules);
490 } // namespace lldb_private
492 #endif // liblldb_ModuleList_h_