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 LLDB_CORE_MODULELIST_H
10 #define LLDB_CORE_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"
23 #include "llvm/Support/RWMutex.h"
33 namespace lldb_private {
39 class RegularExpression;
42 class SymbolContextList;
49 class ModuleListProperties : public Properties {
50 mutable llvm::sys::RWMutex m_symlink_paths_mutex;
51 PathMappingList m_symlink_paths;
53 void UpdateSymlinkMappings();
56 ModuleListProperties();
58 FileSpec GetClangModulesCachePath() const;
59 bool SetClangModulesCachePath(llvm::StringRef path);
60 bool GetEnableExternalLookup() const;
61 bool SetEnableExternalLookup(bool new_value);
63 PathMappingList GetSymlinkMappings() const;
66 /// \class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
67 /// A collection class for Module objects.
69 /// Modules in the module collection class are stored as reference counted
70 /// shared pointers to Module objects.
75 virtual ~Notifier() = default;
77 virtual void NotifyModuleAdded(const ModuleList &module_list,
78 const lldb::ModuleSP &module_sp) = 0;
79 virtual void NotifyModuleRemoved(const ModuleList &module_list,
80 const lldb::ModuleSP &module_sp) = 0;
81 virtual void NotifyModuleUpdated(const ModuleList &module_list,
82 const lldb::ModuleSP &old_module_sp,
83 const lldb::ModuleSP &new_module_sp) = 0;
84 virtual void NotifyWillClearList(const ModuleList &module_list) = 0;
86 virtual void NotifyModulesRemoved(lldb_private::ModuleList &module_list) = 0;
89 /// Default constructor.
91 /// Creates an empty list of Module objects.
96 /// Creates a new module list object with a copy of the modules from \a rhs.
99 /// Another module list object.
100 ModuleList(const ModuleList &rhs);
102 ModuleList(ModuleList::Notifier *notifier);
107 /// Assignment operator.
109 /// Copies the module list from \a rhs into this list.
112 /// Another module list object.
115 /// A const reference to this object.
116 const ModuleList &operator=(const ModuleList &rhs);
118 /// Append a module to the module list.
120 /// \param[in] module_sp
121 /// A shared pointer to a module to add to this collection.
123 /// \param[in] notify
124 /// If true, and a notifier function is set, the notifier function
125 /// will be called. Defaults to true.
127 /// When this ModuleList is the Target's ModuleList, the notifier
128 /// function is Target::ModulesDidLoad -- the call to
129 /// ModulesDidLoad may be deferred when adding multiple Modules
130 /// to the Target, but it must be called at the end,
131 /// before resuming execution.
132 void Append(const lldb::ModuleSP &module_sp, bool notify = true);
134 /// Append a module to the module list and remove any equivalent modules.
135 /// Equivalent modules are ones whose file, platform file and architecture
138 /// Replaces the module to the collection.
140 /// \param[in] module_sp
141 /// A shared pointer to a module to replace in this collection.
142 void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
144 /// Append a module to the module list, if it is not already there.
146 /// \param[in] notify
147 /// If true, and a notifier function is set, the notifier function
148 /// will be called. Defaults to true.
150 /// When this ModuleList is the Target's ModuleList, the notifier
151 /// function is Target::ModulesDidLoad -- the call to
152 /// ModulesDidLoad may be deferred when adding multiple Modules
153 /// to the Target, but it must be called at the end,
154 /// before resuming execution.
155 bool AppendIfNeeded(const lldb::ModuleSP &module_sp, bool notify = true);
157 void Append(const ModuleList &module_list);
159 bool AppendIfNeeded(const ModuleList &module_list);
161 bool ReplaceModule(const lldb::ModuleSP &old_module_sp,
162 const lldb::ModuleSP &new_module_sp);
164 /// Clear the object's state.
166 /// Clears the list of modules and releases a reference to each module
167 /// object and if the reference count goes to zero, the module will be
171 /// Clear the object's state.
173 /// Clears the list of modules and releases a reference to each module
174 /// object and if the reference count goes to zero, the module will be
175 /// deleted. Also release all memory that might be held by any collection
176 /// classes (like std::vector)
179 /// Dump the description of each module contained in this list.
181 /// Dump the description of each module contained in this list to the
182 /// supplied stream \a s.
185 /// The stream to which to dump the object description.
187 /// \see Module::Dump(Stream *) const
188 void Dump(Stream *s) const;
190 void LogUUIDAndPaths(Log *log, const char *prefix_cstr);
192 std::recursive_mutex &GetMutex() const { return m_modules_mutex; }
194 size_t GetIndexForModule(const Module *module) const;
196 /// Get the module shared pointer for the module at index \a idx.
199 /// An index into this module collection.
202 /// A shared pointer to a Module which can contain NULL if
203 /// \a idx is out of range.
205 /// \see ModuleList::GetSize()
206 lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
208 /// Get the module shared pointer for the module at index \a idx without
209 /// acquiring the ModuleList mutex. This MUST already have been acquired
210 /// with ModuleList::GetMutex and locked for this call to be safe.
213 /// An index into this module collection.
216 /// A shared pointer to a Module which can contain NULL if
217 /// \a idx is out of range.
219 /// \see ModuleList::GetSize()
220 lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
222 /// Get the module pointer for the module at index \a idx.
225 /// An index into this module collection.
228 /// A pointer to a Module which can by nullptr if \a idx is out
231 /// \see ModuleList::GetSize()
232 Module *GetModulePointerAtIndex(size_t idx) const;
234 /// Get the module pointer for the module at index \a idx without acquiring
235 /// the ModuleList mutex. This MUST already have been acquired with
236 /// ModuleList::GetMutex and locked for this call to be safe.
239 /// An index into this module collection.
242 /// A pointer to a Module which can by nullptr if \a idx is out
245 /// \see ModuleList::GetSize()
246 Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
248 /// Find compile units by partial or full path.
250 /// Finds all compile units that match \a path in all of the modules and
251 /// returns the results in \a sc_list.
254 /// The name of the compile unit we are looking for.
256 /// \param[out] sc_list
257 /// A symbol context list that gets filled in with all of the
259 void FindCompileUnits(const FileSpec &path, SymbolContextList &sc_list) const;
261 /// \see Module::FindFunctions ()
262 void FindFunctions(ConstString name, lldb::FunctionNameType name_type_mask,
263 bool include_symbols, bool include_inlines,
264 SymbolContextList &sc_list) const;
266 /// \see Module::FindFunctionSymbols ()
267 void FindFunctionSymbols(ConstString name,
268 lldb::FunctionNameType name_type_mask,
269 SymbolContextList &sc_list);
271 /// \see Module::FindFunctions ()
272 void FindFunctions(const RegularExpression &name, bool include_symbols,
273 bool include_inlines, SymbolContextList &sc_list);
275 /// Find global and static variables by name.
278 /// The name of the global or static variable we are looking
281 /// \param[in] max_matches
282 /// Allow the number of matches to be limited to \a
283 /// max_matches. Specify UINT32_MAX to get all possible matches.
285 /// \param[in] variable_list
286 /// A list of variables that gets the matches appended to.
287 void FindGlobalVariables(ConstString name, size_t max_matches,
288 VariableList &variable_list) const;
290 /// Find global and static variables by regular expression.
293 /// A regular expression to use when matching the name.
295 /// \param[in] max_matches
296 /// Allow the number of matches to be limited to \a
297 /// max_matches. Specify UINT32_MAX to get all possible matches.
299 /// \param[in] variable_list
300 /// A list of variables that gets the matches appended to.
301 void FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
302 VariableList &variable_list) const;
304 /// Finds the first module whose file specification matches \a file_spec.
306 /// \param[in] module_spec
307 /// A file specification object to match against the Module's
308 /// file specifications. If \a file_spec does not have
309 /// directory information, matches will occur by matching only
310 /// the basename of any modules in this list. If this value is
311 /// NULL, then file specifications won't be compared when
312 /// searching for matching modules.
314 /// \param[out] matching_module_list
315 /// A module list that gets filled in with any modules that
316 /// match the search criteria.
317 void FindModules(const ModuleSpec &module_spec,
318 ModuleList &matching_module_list) const;
320 lldb::ModuleSP FindModule(const Module *module_ptr) const;
322 // Find a module by UUID
324 // The UUID value for a module is extracted from the ObjectFile and is the
325 // MD5 checksum, or a smarter object file equivalent, so finding modules by
326 // UUID values is very efficient and accurate.
327 lldb::ModuleSP FindModule(const UUID &uuid) const;
329 lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
331 void FindSymbolsWithNameAndType(ConstString name,
332 lldb::SymbolType symbol_type,
333 SymbolContextList &sc_list) const;
335 void FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
336 lldb::SymbolType symbol_type,
337 SymbolContextList &sc_list) const;
339 /// Find types by name.
341 /// \param[in] search_first
342 /// If non-null, this module will be searched before any other
346 /// The name of the type we are looking for.
348 /// \param[in] max_matches
349 /// Allow the number of matches to be limited to \a
350 /// max_matches. Specify UINT32_MAX to get all possible matches.
352 /// \param[out] types
353 /// A type list gets populated with any matches.
355 void FindTypes(Module *search_first, ConstString name,
356 bool name_is_fully_qualified, size_t max_matches,
357 llvm::DenseSet<SymbolFile *> &searched_symbol_files,
358 TypeList &types) const;
360 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
362 /// Find addresses by file/line
364 /// \param[in] target_sp
365 /// The target the addresses are desired for.
368 /// Source file to locate.
371 /// Source line to locate.
373 /// \param[in] function
374 /// Optional filter function. Addresses within this function will be
375 /// added to the 'local' list. All others will be added to the 'extern'
378 /// \param[out] output_local
379 /// All matching addresses within 'function'
381 /// \param[out] output_extern
382 /// All matching addresses not within 'function'
383 void FindAddressesForLine(const lldb::TargetSP target_sp,
384 const FileSpec &file, uint32_t line,
386 std::vector<Address> &output_local,
387 std::vector<Address> &output_extern);
389 /// Remove a module from the module list.
391 /// \param[in] module_sp
392 /// A shared pointer to a module to remove from this collection.
394 /// \param[in] notify
395 /// If true, and a notifier function is set, the notifier function
396 /// will be called. Defaults to true.
398 /// When this ModuleList is the Target's ModuleList, the notifier
399 /// function is Target::ModulesDidUnload -- the call to
400 /// ModulesDidUnload may be deferred when removing multiple Modules
401 /// from the Target, but it must be called at the end,
402 /// before resuming execution.
403 bool Remove(const lldb::ModuleSP &module_sp, bool notify = true);
405 size_t Remove(ModuleList &module_list);
407 bool RemoveIfOrphaned(const Module *module_ptr);
409 size_t RemoveOrphans(bool mandatory);
411 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
413 /// \copydoc Module::ResolveSymbolContextForAddress (const Address
414 /// &,uint32_t,SymbolContext&)
415 uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
416 lldb::SymbolContextItem resolve_scope,
417 SymbolContext &sc) const;
419 /// \copydoc Module::ResolveSymbolContextForFilePath (const char
420 /// *,uint32_t,bool,uint32_t,SymbolContextList&)
421 uint32_t ResolveSymbolContextForFilePath(
422 const char *file_path, uint32_t line, bool check_inlines,
423 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
425 /// \copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
426 /// &,uint32_t,bool,uint32_t,SymbolContextList&)
427 uint32_t ResolveSymbolContextsForFileSpec(
428 const FileSpec &file_spec, uint32_t line, bool check_inlines,
429 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list) const;
431 /// Gets the size of the module list.
434 /// The number of modules in the module list.
435 size_t GetSize() const;
436 bool IsEmpty() const { return !GetSize(); }
438 bool LoadScriptingResourcesInTarget(Target *target, std::list<Status> &errors,
439 Stream *feedback_stream = nullptr,
440 bool continue_on_error = true);
442 static ModuleListProperties &GetGlobalModuleListProperties();
444 static bool ModuleIsInCache(const Module *module_ptr);
446 static Status GetSharedModule(const ModuleSpec &module_spec,
447 lldb::ModuleSP &module_sp,
448 const FileSpecList *module_search_paths_ptr,
449 lldb::ModuleSP *old_module_sp_ptr,
450 bool *did_create_ptr,
451 bool always_create = false);
453 static bool RemoveSharedModule(lldb::ModuleSP &module_sp);
455 static void FindSharedModules(const ModuleSpec &module_spec,
456 ModuleList &matching_module_list);
458 static size_t RemoveOrphanSharedModules(bool mandatory);
460 static bool RemoveSharedModuleIfOrphaned(const Module *module_ptr);
462 void ForEach(std::function<bool(const lldb::ModuleSP &module_sp)> const
467 typedef std::vector<lldb::ModuleSP>
468 collection; ///< The module collection type.
470 void AppendImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
472 bool RemoveImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
474 collection::iterator RemoveImpl(collection::iterator pos,
475 bool use_notifier = true);
477 void ClearImpl(bool use_notifier = true);
480 collection m_modules; ///< The collection of modules.
481 mutable std::recursive_mutex m_modules_mutex;
483 Notifier *m_notifier;
486 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter,
487 std::recursive_mutex>
489 ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); }
491 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter>
492 ModuleIterableNoLocking;
493 ModuleIterableNoLocking ModulesNoLocking() {
494 return ModuleIterableNoLocking(m_modules);
498 } // namespace lldb_private
500 #endif // LLDB_CORE_MODULELIST_H