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/Utility/FileSpec.h" // for FileSpec
16 #include "lldb/Utility/Iterable.h"
17 #include "lldb/Utility/Status.h" // for Status
18 #include "lldb/lldb-enumerations.h"
19 #include "lldb/lldb-forward.h"
20 #include "lldb/lldb-types.h"
22 #include "llvm/ADT/DenseSet.h"
29 #include <stddef.h> // for size_t
30 #include <stdint.h> // for uint32_t
32 namespace lldb_private {
35 namespace lldb_private {
38 namespace lldb_private {
41 namespace lldb_private {
44 namespace lldb_private {
47 namespace lldb_private {
48 class RegularExpression;
50 namespace lldb_private {
53 namespace lldb_private {
56 namespace lldb_private {
57 class SymbolContextList;
59 namespace lldb_private {
62 namespace lldb_private {
65 namespace lldb_private {
68 namespace lldb_private {
71 namespace lldb_private {
75 namespace lldb_private {
77 //----------------------------------------------------------------------
78 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
79 /// @brief A collection class for Module objects.
81 /// Modules in the module collection class are stored as reference
82 /// counted shared pointers to Module objects.
83 //----------------------------------------------------------------------
88 virtual ~Notifier() = default;
90 virtual void ModuleAdded(const ModuleList &module_list,
91 const lldb::ModuleSP &module_sp) = 0;
92 virtual void ModuleRemoved(const ModuleList &module_list,
93 const lldb::ModuleSP &module_sp) = 0;
94 virtual void ModuleUpdated(const ModuleList &module_list,
95 const lldb::ModuleSP &old_module_sp,
96 const lldb::ModuleSP &new_module_sp) = 0;
97 virtual void WillClearList(const ModuleList &module_list) = 0;
100 //------------------------------------------------------------------
101 /// Default constructor.
103 /// Creates an empty list of Module objects.
104 //------------------------------------------------------------------
107 //------------------------------------------------------------------
108 /// Copy Constructor.
110 /// Creates a new module list object with a copy of the modules from
114 /// Another module list object.
115 //------------------------------------------------------------------
116 ModuleList(const ModuleList &rhs);
118 ModuleList(ModuleList::Notifier *notifier);
120 //------------------------------------------------------------------
122 //------------------------------------------------------------------
125 //------------------------------------------------------------------
126 /// Assignment operator.
128 /// Copies the module list from \a rhs into this list.
131 /// Another module list object.
134 /// A const reference to this object.
135 //------------------------------------------------------------------
136 const ModuleList &operator=(const ModuleList &rhs);
138 //------------------------------------------------------------------
139 /// Append a module to the module list.
141 /// Appends the module to the collection.
143 /// @param[in] module_sp
144 /// A shared pointer to a module to add to this collection.
145 //------------------------------------------------------------------
146 void Append(const lldb::ModuleSP &module_sp);
148 //------------------------------------------------------------------
149 /// Append a module to the module list and remove any equivalent
150 /// modules. Equivalent modules are ones whose file, platform file
151 /// and architecture matches.
153 /// Replaces the module to the collection.
155 /// @param[in] module_sp
156 /// A shared pointer to a module to replace in this collection.
157 //------------------------------------------------------------------
158 void ReplaceEquivalent(const lldb::ModuleSP &module_sp);
160 bool AppendIfNeeded(const lldb::ModuleSP &module_sp);
162 void Append(const ModuleList &module_list);
164 bool AppendIfNeeded(const ModuleList &module_list);
166 bool ReplaceModule(const lldb::ModuleSP &old_module_sp,
167 const lldb::ModuleSP &new_module_sp);
169 //------------------------------------------------------------------
170 /// Clear the object's state.
172 /// Clears the list of modules and releases a reference to each
173 /// module object and if the reference count goes to zero, the
174 /// module will be deleted.
175 //------------------------------------------------------------------
178 //------------------------------------------------------------------
179 /// Clear the object's state.
181 /// Clears the list of modules and releases a reference to each
182 /// module object and if the reference count goes to zero, the
183 /// module will be deleted. Also release all memory that might be
184 /// held by any collection classes (like std::vector)
185 //------------------------------------------------------------------
188 //------------------------------------------------------------------
189 /// Dump the description of each module contained in this list.
191 /// Dump the description of each module contained in this list to
192 /// the supplied stream \a s.
195 /// The stream to which to dump the object description.
197 /// @see Module::Dump(Stream *) const
198 //------------------------------------------------------------------
199 void Dump(Stream *s) const;
201 void LogUUIDAndPaths(Log *log, const char *prefix_cstr);
203 std::recursive_mutex &GetMutex() const { return m_modules_mutex; }
205 size_t GetIndexForModule(const Module *module) const;
207 //------------------------------------------------------------------
208 /// Get the module shared pointer for the module at index \a idx.
211 /// An index into this module collection.
214 /// A shared pointer to a Module which can contain NULL if
215 /// \a idx is out of range.
217 /// @see ModuleList::GetSize()
218 //------------------------------------------------------------------
219 lldb::ModuleSP GetModuleAtIndex(size_t idx) const;
221 //------------------------------------------------------------------
222 /// Get the module shared pointer for the module at index \a idx without
223 /// acquiring the ModuleList mutex. This MUST already have been
224 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
227 /// An index into this module collection.
230 /// A shared pointer to a Module which can contain NULL if
231 /// \a idx is out of range.
233 /// @see ModuleList::GetSize()
234 //------------------------------------------------------------------
235 lldb::ModuleSP GetModuleAtIndexUnlocked(size_t idx) const;
237 //------------------------------------------------------------------
238 /// Get the module pointer for the module at index \a idx.
241 /// An index into this module collection.
244 /// A pointer to a Module which can by nullptr if \a idx is out
247 /// @see ModuleList::GetSize()
248 //------------------------------------------------------------------
249 Module *GetModulePointerAtIndex(size_t idx) const;
251 //------------------------------------------------------------------
252 /// Get the module pointer for the module at index \a idx without
253 /// acquiring the ModuleList mutex. This MUST already have been
254 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
257 /// An index into this module collection.
260 /// A pointer to a Module which can by nullptr if \a idx is out
263 /// @see ModuleList::GetSize()
264 //------------------------------------------------------------------
265 Module *GetModulePointerAtIndexUnlocked(size_t idx) const;
267 //------------------------------------------------------------------
268 /// Find compile units by partial or full path.
270 /// Finds all compile units that match \a path in all of the modules
271 /// and returns the results in \a sc_list.
274 /// The name of the compile unit we are looking for.
276 /// @param[in] append
277 /// If \b true, then append any compile units that were found
278 /// to \a sc_list. If \b false, then the \a sc_list is cleared
279 /// and the contents of \a sc_list are replaced.
281 /// @param[out] sc_list
282 /// A symbol context list that gets filled in with all of the
286 /// The number of matches added to \a sc_list.
287 //------------------------------------------------------------------
288 size_t FindCompileUnits(const FileSpec &path, bool append,
289 SymbolContextList &sc_list) const;
291 //------------------------------------------------------------------
292 /// @see Module::FindFunctions ()
293 //------------------------------------------------------------------
294 size_t FindFunctions(const ConstString &name, uint32_t name_type_mask,
295 bool include_symbols, bool include_inlines, bool append,
296 SymbolContextList &sc_list) const;
298 //------------------------------------------------------------------
299 /// @see Module::FindFunctionSymbols ()
300 //------------------------------------------------------------------
301 size_t FindFunctionSymbols(const ConstString &name, uint32_t name_type_mask,
302 SymbolContextList &sc_list);
304 //------------------------------------------------------------------
305 /// @see Module::FindFunctions ()
306 //------------------------------------------------------------------
307 size_t FindFunctions(const RegularExpression &name, bool include_symbols,
308 bool include_inlines, bool append,
309 SymbolContextList &sc_list);
311 //------------------------------------------------------------------
312 /// Find global and static variables by name.
315 /// The name of the global or static variable we are looking
318 /// @param[in] append
319 /// If \b true, any matches will be appended to \a
320 /// variable_list, else matches replace the contents of
321 /// \a variable_list.
323 /// @param[in] max_matches
324 /// Allow the number of matches to be limited to \a
325 /// max_matches. Specify UINT32_MAX to get all possible matches.
327 /// @param[in] variable_list
328 /// A list of variables that gets the matches appended to (if
329 /// \a append it \b true), or replace (if \a append is \b false).
332 /// The number of matches added to \a variable_list.
333 //------------------------------------------------------------------
334 size_t FindGlobalVariables(const ConstString &name, bool append,
336 VariableList &variable_list) const;
338 //------------------------------------------------------------------
339 /// Find global and static variables by regular expression.
342 /// A regular expression to use when matching the name.
344 /// @param[in] append
345 /// If \b true, any matches will be appended to \a
346 /// variable_list, else matches replace the contents of
347 /// \a variable_list.
349 /// @param[in] max_matches
350 /// Allow the number of matches to be limited to \a
351 /// max_matches. Specify UINT32_MAX to get all possible matches.
353 /// @param[in] variable_list
354 /// A list of variables that gets the matches appended to (if
355 /// \a append it \b true), or replace (if \a append is \b false).
358 /// The number of matches added to \a variable_list.
359 //------------------------------------------------------------------
360 size_t FindGlobalVariables(const RegularExpression ®ex, bool append,
362 VariableList &variable_list) const;
364 //------------------------------------------------------------------
365 /// Finds the first module whose file specification matches \a
368 /// @param[in] file_spec_ptr
369 /// A file specification object to match against the Module's
370 /// file specifications. If \a file_spec does not have
371 /// directory information, matches will occur by matching only
372 /// the basename of any modules in this list. If this value is
373 /// NULL, then file specifications won't be compared when
374 /// searching for matching modules.
376 /// @param[in] arch_ptr
377 /// The architecture to search for if non-NULL. If this value
378 /// is NULL no architecture matching will be performed.
380 /// @param[in] uuid_ptr
381 /// The uuid to search for if non-NULL. If this value is NULL
382 /// no uuid matching will be performed.
384 /// @param[in] object_name
385 /// An optional object name that must match as well. This value
388 /// @param[out] matching_module_list
389 /// A module list that gets filled in with any modules that
390 /// match the search criteria.
393 /// The number of matching modules found by the search.
394 //------------------------------------------------------------------
395 size_t FindModules(const ModuleSpec &module_spec,
396 ModuleList &matching_module_list) const;
398 lldb::ModuleSP FindModule(const Module *module_ptr) const;
400 //------------------------------------------------------------------
401 // Find a module by UUID
403 // The UUID value for a module is extracted from the ObjectFile and
404 // is the MD5 checksum, or a smarter object file equivalent, so
405 // finding modules by UUID values is very efficient and accurate.
406 //------------------------------------------------------------------
407 lldb::ModuleSP FindModule(const UUID &uuid) const;
409 lldb::ModuleSP FindFirstModule(const ModuleSpec &module_spec) const;
411 size_t FindSymbolsWithNameAndType(const ConstString &name,
412 lldb::SymbolType symbol_type,
413 SymbolContextList &sc_list,
414 bool append = false) const;
416 size_t FindSymbolsMatchingRegExAndType(const RegularExpression ®ex,
417 lldb::SymbolType symbol_type,
418 SymbolContextList &sc_list,
419 bool append = false) const;
421 //------------------------------------------------------------------
422 /// Find types by name.
425 /// A symbol context that scopes where to extract a type list
429 /// The name of the type we are looking for.
431 /// @param[in] append
432 /// If \b true, any matches will be appended to \a
433 /// variable_list, else matches replace the contents of
434 /// \a variable_list.
436 /// @param[in] max_matches
437 /// Allow the number of matches to be limited to \a
438 /// max_matches. Specify UINT32_MAX to get all possible matches.
440 /// @param[in] encoding
441 /// Limit the search to specific types, or get all types if
442 /// set to Type::invalid.
444 /// @param[in] udt_name
445 /// If the encoding is a user defined type, specify the name
446 /// of the user defined type ("struct", "union", "class", etc).
448 /// @param[out] type_list
449 /// A type list gets populated with any matches.
452 /// The number of matches added to \a type_list.
453 //------------------------------------------------------------------
454 size_t FindTypes(const SymbolContext &sc, const ConstString &name,
455 bool name_is_fully_qualified, size_t max_matches,
456 llvm::DenseSet<SymbolFile *> &searched_symbol_files,
457 TypeList &types) const;
459 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
461 //------------------------------------------------------------------
462 /// Find addresses by file/line
464 /// @param[in] target_sp
465 /// The target the addresses are desired for.
468 /// Source file to locate.
471 /// Source line to locate.
473 /// @param[in] function
474 /// Optional filter function. Addresses within this function will be
475 /// added to the 'local' list. All others will be added to the 'extern'
478 /// @param[out] output_local
479 /// All matching addresses within 'function'
481 /// @param[out] output_extern
482 /// All matching addresses not within 'function'
483 void FindAddressesForLine(const lldb::TargetSP target_sp,
484 const FileSpec &file, uint32_t line,
486 std::vector<Address> &output_local,
487 std::vector<Address> &output_extern);
489 bool Remove(const lldb::ModuleSP &module_sp);
491 size_t Remove(ModuleList &module_list);
493 bool RemoveIfOrphaned(const Module *module_ptr);
495 size_t RemoveOrphans(bool mandatory);
497 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr) const;
499 //------------------------------------------------------------------
500 /// @copydoc Module::ResolveSymbolContextForAddress (const Address
501 /// &,uint32_t,SymbolContext&)
502 //------------------------------------------------------------------
503 uint32_t ResolveSymbolContextForAddress(const Address &so_addr,
504 uint32_t resolve_scope,
505 SymbolContext &sc) const;
507 //------------------------------------------------------------------
508 /// @copydoc Module::ResolveSymbolContextForFilePath (const char
509 /// *,uint32_t,bool,uint32_t,SymbolContextList&)
510 //------------------------------------------------------------------
511 uint32_t ResolveSymbolContextForFilePath(const char *file_path, uint32_t line,
513 uint32_t resolve_scope,
514 SymbolContextList &sc_list) const;
516 //------------------------------------------------------------------
517 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec
518 /// &,uint32_t,bool,uint32_t,SymbolContextList&)
519 //------------------------------------------------------------------
520 uint32_t ResolveSymbolContextsForFileSpec(const FileSpec &file_spec,
521 uint32_t line, bool check_inlines,
522 uint32_t resolve_scope,
523 SymbolContextList &sc_list) const;
525 //------------------------------------------------------------------
526 /// Gets the size of the module list.
529 /// The number of modules in the module list.
530 //------------------------------------------------------------------
531 size_t GetSize() const;
533 bool LoadScriptingResourcesInTarget(Target *target, std::list<Status> &errors,
534 Stream *feedback_stream = nullptr,
535 bool continue_on_error = true);
537 static bool ModuleIsInCache(const Module *module_ptr);
539 static Status GetSharedModule(const ModuleSpec &module_spec,
540 lldb::ModuleSP &module_sp,
541 const FileSpecList *module_search_paths_ptr,
542 lldb::ModuleSP *old_module_sp_ptr,
543 bool *did_create_ptr,
544 bool always_create = false);
546 static bool RemoveSharedModule(lldb::ModuleSP &module_sp);
548 static size_t FindSharedModules(const ModuleSpec &module_spec,
549 ModuleList &matching_module_list);
551 static size_t RemoveOrphanSharedModules(bool mandatory);
553 static bool RemoveSharedModuleIfOrphaned(const Module *module_ptr);
555 void ForEach(std::function<bool(const lldb::ModuleSP &module_sp)> const
559 //------------------------------------------------------------------
561 //------------------------------------------------------------------
562 typedef std::vector<lldb::ModuleSP>
563 collection; ///< The module collection type.
565 void AppendImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
567 bool RemoveImpl(const lldb::ModuleSP &module_sp, bool use_notifier = true);
569 collection::iterator RemoveImpl(collection::iterator pos,
570 bool use_notifier = true);
572 void ClearImpl(bool use_notifier = true);
574 //------------------------------------------------------------------
576 //------------------------------------------------------------------
577 collection m_modules; ///< The collection of modules.
578 mutable std::recursive_mutex m_modules_mutex;
580 Notifier *m_notifier;
583 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter,
584 std::recursive_mutex>
586 ModuleIterable Modules() { return ModuleIterable(m_modules, GetMutex()); }
588 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter>
589 ModuleIterableNoLocking;
590 ModuleIterableNoLocking ModulesNoLocking() {
591 return ModuleIterableNoLocking(m_modules);
595 } // namespace lldb_private
597 #endif // liblldb_ModuleList_h_