1 //===-- ModuleList.h --------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ModuleList_h_
11 #define liblldb_ModuleList_h_
13 #include "lldb/Core/Address.h" // for Address
14 #include "lldb/Core/ModuleSpec.h" // for ModuleSpec
15 #include "lldb/Core/UserSettingsController.h"
16 #include "lldb/Utility/FileSpec.h" // for FileSpec
17 #include "lldb/Utility/Iterable.h"
18 #include "lldb/Utility/Status.h" // for Status
19 #include "lldb/lldb-enumerations.h"
20 #include "lldb/lldb-forward.h"
21 #include "lldb/lldb-types.h"
23 #include "llvm/ADT/DenseSet.h"
30 #include <stddef.h> // for size_t
31 #include <stdint.h> // for uint32_t
33 namespace lldb_private {
36 namespace lldb_private {
39 namespace lldb_private {
42 namespace lldb_private {
45 namespace lldb_private {
48 namespace lldb_private {
49 class RegularExpression;
51 namespace lldb_private {
54 namespace lldb_private {
57 namespace lldb_private {
58 class SymbolContextList;
60 namespace lldb_private {
63 namespace lldb_private {
66 namespace lldb_private {
69 namespace lldb_private {
72 namespace lldb_private {
76 namespace lldb_private {
78 class ModuleListProperties : public Properties {
80 ModuleListProperties();
82 FileSpec GetClangModulesCachePath() const;
83 bool SetClangModulesCachePath(llvm::StringRef path);
84 bool GetEnableExternalLookup() const;
87 //----------------------------------------------------------------------
88 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
89 /// A collection class for Module objects.
91 /// Modules in the module collection class are stored as reference counted
92 /// shared pointers to Module objects.
93 //----------------------------------------------------------------------
98 virtual ~Notifier() = default;
100 virtual void ModuleAdded(const ModuleList &module_list,
101 const lldb::ModuleSP &module_sp) = 0;
102 virtual void ModuleRemoved(const ModuleList &module_list,
103 const lldb::ModuleSP &module_sp) = 0;
104 virtual void ModuleUpdated(const ModuleList &module_list,
105 const lldb::ModuleSP &old_module_sp,
106 const lldb::ModuleSP &new_module_sp) = 0;
107 virtual void WillClearList(const ModuleList &module_list) = 0;
110 //------------------------------------------------------------------
111 /// Default constructor.
113 /// Creates an empty list of Module objects.
114 //------------------------------------------------------------------
117 //------------------------------------------------------------------
118 /// Copy Constructor.
120 /// Creates a new module list object with a copy of the modules from \a rhs.
123 /// Another module list object.
124 //------------------------------------------------------------------
125 ModuleList(const ModuleList &rhs);
127 ModuleList(ModuleList::Notifier *notifier);
129 //------------------------------------------------------------------
131 //------------------------------------------------------------------
134 //------------------------------------------------------------------
135 /// Assignment operator.
137 /// Copies the module list from \a rhs into this list.
140 /// Another module list object.
143 /// A const reference to this object.
144 //------------------------------------------------------------------
145 const ModuleList &operator=(const ModuleList &rhs);
147 //------------------------------------------------------------------
148 /// Append a module to the module list.
150 /// Appends the module to the collection.
152 /// @param[in] module_sp
153 /// A shared pointer to a module to add to this collection.
154 //------------------------------------------------------------------
155 void Append(const lldb::ModuleSP &module_sp);
157 //------------------------------------------------------------------
158 /// Append a module to the module list and remove any equivalent modules.
159 /// Equivalent modules are ones whose file, platform file and architecture
162 /// Replaces the module to the collection.
164 /// @param[in] module_sp
165 /// A shared pointer to a module to replace in this collection.
166 //------------------------------------------------------------------
167 void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
169 bool AppendIfNeeded(const lldb::ModuleSP &module_sp);
171 void Append(const ModuleList &module_list);
173 bool AppendIfNeeded(const ModuleList &module_list);
175 bool ReplaceModule(const lldb::ModuleSP &old_module_sp,
176 const lldb::ModuleSP &new_module_sp);
178 //------------------------------------------------------------------
179 /// Clear the object's state.
181 /// Clears the list of modules and releases a reference to each module
182 /// object and if the reference count goes to zero, the module will be
184 //------------------------------------------------------------------
187 //------------------------------------------------------------------
188 /// Clear the object's state.
190 /// Clears the list of modules and releases a reference to each module
191 /// object and if the reference count goes to zero, the module will be
192 /// deleted. Also release all memory that might be held by any collection
193 /// classes (like std::vector)
194 //------------------------------------------------------------------
197 //------------------------------------------------------------------
198 /// Dump the description of each module contained in this list.
200 /// Dump the description of each module contained in this list to the
201 /// supplied stream \a s.
204 /// The stream to which to dump the object description.
206 /// @see Module::Dump(Stream *) const
207 //------------------------------------------------------------------
208 void Dump(Stream *s) const;
210 void LogUUIDAndPaths(Log *log, const char *prefix_cstr);
212 std::recursive_mutex &GetMutex() const { return m_modules_mutex; }
214 size_t GetIndexForModule(const Module *module) const;
216 //------------------------------------------------------------------
217 /// Get the module shared pointer for the module at index \a idx.
220 /// An index into this module collection.
223 /// A shared pointer to a Module which can contain NULL if
224 /// \a idx is out of range.
226 /// @see ModuleList::GetSize()
227 //------------------------------------------------------------------
228 lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
230 //------------------------------------------------------------------
231 /// Get the module shared pointer for the module at index \a idx without
232 /// acquiring the ModuleList mutex. This MUST already have been acquired
233 /// with ModuleList::GetMutex and locked for this call to be safe.
236 /// An index into this module collection.
239 /// A shared pointer to a Module which can contain NULL if
240 /// \a idx is out of range.
242 /// @see ModuleList::GetSize()
243 //------------------------------------------------------------------
244 lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
246 //------------------------------------------------------------------
247 /// Get the module pointer for the module at index \a idx.
250 /// An index into this module collection.
253 /// A pointer to a Module which can by nullptr if \a idx is out
256 /// @see ModuleList::GetSize()
257 //------------------------------------------------------------------
258 Module *GetModulePointerAtIndex(size_t idx) const;
260 //------------------------------------------------------------------
261 /// Get the module pointer for the module at index \a idx without acquiring
262 /// the ModuleList mutex. This MUST already have been acquired with
263 /// ModuleList::GetMutex and locked for this call to be safe.
266 /// An index into this module collection.
269 /// A pointer to a Module which can by nullptr if \a idx is out
272 /// @see ModuleList::GetSize()
273 //------------------------------------------------------------------
274 Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
276 //------------------------------------------------------------------
277 /// Find compile units by partial or full path.
279 /// Finds all compile units that match \a path in all of the modules and
280 /// returns the results in \a sc_list.
283 /// The name of the compile unit we are looking for.
285 /// @param[in] append
286 /// If \b true, then append any compile units that were found
287 /// to \a sc_list. If \b false, then the \a sc_list is cleared
288 /// and the contents of \a sc_list are replaced.
290 /// @param[out] sc_list
291 /// A symbol context list that gets filled in with all of the
295 /// The number of matches added to \a sc_list.
296 //------------------------------------------------------------------
297 size_t FindCompileUnits(const FileSpec &path, bool append,
298 SymbolContextList &sc_list) const;
300 //------------------------------------------------------------------
301 /// @see Module::FindFunctions ()
302 //------------------------------------------------------------------
303 size_t FindFunctions(const ConstString &name, uint32_t name_type_mask,
304 bool include_symbols, bool include_inlines, bool append,
305 SymbolContextList &sc_list) const;
307 //------------------------------------------------------------------
308 /// @see Module::FindFunctionSymbols ()
309 //------------------------------------------------------------------
310 size_t FindFunctionSymbols(const ConstString &name, uint32_t name_type_mask,
311 SymbolContextList &sc_list);
313 //------------------------------------------------------------------
314 /// @see Module::FindFunctions ()
315 //------------------------------------------------------------------
316 size_t FindFunctions(const RegularExpression &name, bool include_symbols,
317 bool include_inlines, bool append,
318 SymbolContextList &sc_list);
320 //------------------------------------------------------------------
321 /// Find global and static variables by name.
324 /// The name of the global or static variable we are looking
327 /// @param[in] max_matches
328 /// Allow the number of matches to be limited to \a
329 /// max_matches. Specify UINT32_MAX to get all possible matches.
331 /// @param[in] variable_list
332 /// A list of variables that gets the matches appended to.
335 /// The number of matches added to \a variable_list.
336 //------------------------------------------------------------------
337 size_t FindGlobalVariables(const ConstString &name, size_t max_matches,
338 VariableList &variable_list) const;
340 //------------------------------------------------------------------
341 /// Find global and static variables by regular expression.
344 /// A regular expression to use when matching the name.
346 /// @param[in] max_matches
347 /// Allow the number of matches to be limited to \a
348 /// max_matches. Specify UINT32_MAX to get all possible matches.
350 /// @param[in] variable_list
351 /// A list of variables that gets the matches appended to.
354 /// The number of matches added to \a variable_list.
355 //------------------------------------------------------------------
356 size_t FindGlobalVariables(const RegularExpression ®ex, size_t max_matches,
357 VariableList &variable_list) const;
359 //------------------------------------------------------------------
360 /// Finds the first module whose file specification matches \a file_spec.
362 /// @param[in] file_spec_ptr
363 /// A file specification object to match against the Module's
364 /// file specifications. If \a file_spec does not have
365 /// directory information, matches will occur by matching only
366 /// the basename of any modules in this list. If this value is
367 /// NULL, then file specifications won't be compared when
368 /// searching for matching modules.
370 /// @param[in] arch_ptr
371 /// The architecture to search for if non-NULL. If this value
372 /// is NULL no architecture matching will be performed.
374 /// @param[in] uuid_ptr
375 /// The uuid to search for if non-NULL. If this value is NULL
376 /// no uuid matching will be performed.
378 /// @param[in] object_name
379 /// An optional object name that must match as well. This value
382 /// @param[out] matching_module_list
383 /// A module list that gets filled in with any modules that
384 /// match the search criteria.
387 /// The number of matching modules found by the search.
388 //------------------------------------------------------------------
389 size_t FindModules(const ModuleSpec &module_spec,
390 ModuleList &matching_module_list) const;
392 lldb::ModuleSP FindModule(const Module *module_ptr) const;
394 //------------------------------------------------------------------
395 // Find a module by UUID
397 // The UUID value for a module is extracted from the ObjectFile and is the
398 // MD5 checksum, or a smarter object file equivalent, so finding modules by
399 // UUID values is very efficient and accurate.
400 //------------------------------------------------------------------
401 lldb::ModuleSP FindModule(const UUID &uuid) const;
403 lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
405 size_t FindSymbolsWithNameAndType(const ConstString &name,
406 lldb::SymbolType symbol_type,
407 SymbolContextList &sc_list,
408 bool append = false) const;
410 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
411 lldb::SymbolType symbol_type,
412 SymbolContextList &sc_list,
413 bool append = false) const;
415 //------------------------------------------------------------------
416 /// Find types by name.
419 /// A symbol context that scopes where to extract a type list
423 /// The name of the type we are looking for.
425 /// @param[in] append
426 /// If \b true, any matches will be appended to \a
427 /// variable_list, else matches replace the contents of
428 /// \a variable_list.
430 /// @param[in] max_matches
431 /// Allow the number of matches to be limited to \a
432 /// max_matches. Specify UINT32_MAX to get all possible matches.
434 /// @param[in] encoding
435 /// Limit the search to specific types, or get all types if
436 /// set to Type::invalid.
438 /// @param[in] udt_name
439 /// If the encoding is a user defined type, specify the name
440 /// of the user defined type ("struct", "union", "class", etc).
442 /// @param[out] type_list
443 /// A type list gets populated with any matches.
446 /// The number of matches added to \a type_list.
447 //------------------------------------------------------------------
448 size_t FindTypes(const SymbolContext &sc, const ConstString &name,
449 bool name_is_fully_qualified, size_t max_matches,
450 llvm::DenseSet<SymbolFile *> &searched_symbol_files,
451 TypeList &types) const;
453 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
455 //------------------------------------------------------------------
456 /// Find addresses by file/line
458 /// @param[in] target_sp
459 /// The target the addresses are desired for.
462 /// Source file to locate.
465 /// Source line to locate.
467 /// @param[in] function
468 /// Optional filter function. Addresses within this function will be
469 /// added to the 'local' list. All others will be added to the 'extern'
472 /// @param[out] output_local
473 /// All matching addresses within 'function'
475 /// @param[out] output_extern
476 /// All matching addresses not within 'function'
477 void FindAddressesForLine(const lldb::TargetSP target_sp,
478 const FileSpec &file, uint32_t line,
480 std::vector<Address> &output_local,
481 std::vector<Address> &output_extern);
483 bool Remove(const lldb::ModuleSP &module_sp);
485 size_t Remove(ModuleList &module_list);
487 bool RemoveIfOrphaned(const Module *module_ptr);
489 size_t RemoveOrphans(bool mandatory);
491 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
493 //------------------------------------------------------------------
494 /// @copydoc Module::ResolveSymbolContextForAddress (const Address
495 /// &,uint32_t,SymbolContext&)
496 //------------------------------------------------------------------
497 uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
498 uint32_t resolve_scope,
499 SymbolContext &sc) const;
501 //------------------------------------------------------------------
502 /// @copydoc Module::ResolveSymbolContextForFilePath (const char
503 /// *,uint32_t,bool,uint32_t,SymbolContextList&)
504 //------------------------------------------------------------------
505 uint32_t ResolveSymbolContextForFilePath(const char *file_path, uint32_t line,
507 uint32_t resolve_scope,
508 SymbolContextList &sc_list) const;
510 //------------------------------------------------------------------
511 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
512 /// &,uint32_t,bool,uint32_t,SymbolContextList&)
513 //------------------------------------------------------------------
514 uint32_t ResolveSymbolContextsForFileSpec(const FileSpec &file_spec,
515 uint32_t line, bool check_inlines,
516 uint32_t resolve_scope,
517 SymbolContextList &sc_list) const;
519 //------------------------------------------------------------------
520 /// Gets the size of the module list.
523 /// The number of modules in the module list.
524 //------------------------------------------------------------------
525 size_t GetSize() const;
527 bool LoadScriptingResourcesInTarget(Target *target, std::list<Status> &errors,
528 Stream *feedback_stream = nullptr,
529 bool continue_on_error = true);
531 static ModuleListProperties &GetGlobalModuleListProperties();
533 static bool ModuleIsInCache(const Module *module_ptr);
535 static Status GetSharedModule(const ModuleSpec &module_spec,
536 lldb::ModuleSP &module_sp,
537 const FileSpecList *module_search_paths_ptr,
538 lldb::ModuleSP *old_module_sp_ptr,
539 bool *did_create_ptr,
540 bool always_create = false);
542 static bool RemoveSharedModule(lldb::ModuleSP &module_sp);
544 static size_t FindSharedModules(const ModuleSpec &module_spec,
545 ModuleList &matching_module_list);
547 static size_t RemoveOrphanSharedModules(bool mandatory);
549 static bool RemoveSharedModuleIfOrphaned(const Module *module_ptr);
551 void ForEach(std::function<bool(const lldb::ModuleSP &module_sp)> const
555 //------------------------------------------------------------------
557 //------------------------------------------------------------------
558 typedef std::vector<lldb::ModuleSP>
559 collection; ///< The module collection type.
561 void AppendImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
563 bool RemoveImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
565 collection::iterator RemoveImpl(collection::iterator pos,
566 bool use_notifier = true);
568 void ClearImpl(bool use_notifier = true);
570 //------------------------------------------------------------------
572 //------------------------------------------------------------------
573 collection m_modules; ///< The collection of modules.
574 mutable std::recursive_mutex m_modules_mutex;
576 Notifier *m_notifier;
579 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter,
580 std::recursive_mutex>
582 ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); }
584 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter>
585 ModuleIterableNoLocking;
586 ModuleIterableNoLocking ModulesNoLocking() {
587 return ModuleIterableNoLocking(m_modules);
591 } // namespace lldb_private
593 #endif // liblldb_ModuleList_h_