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_
16 #include "lldb/lldb-private.h"
17 #include "lldb/Host/Mutex.h"
18 #include "lldb/Utility/Iterable.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
24 /// @brief A collection class for Module objects.
26 /// Modules in the module collection class are stored as reference
27 /// counted shared pointers to Module objects.
28 //----------------------------------------------------------------------
37 ModuleAdded (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
39 ModuleRemoved (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
41 ModuleUpdated (const ModuleList& module_list, const lldb::ModuleSP& old_module_sp,
42 const lldb::ModuleSP& new_module_sp) = 0;
44 WillClearList (const ModuleList& module_list) = 0;
51 //------------------------------------------------------------------
52 /// Default constructor.
54 /// Creates an empty list of Module objects.
55 //------------------------------------------------------------------
58 //------------------------------------------------------------------
61 /// Creates a new module list object with a copy of the modules from
65 /// Another module list object.
66 //------------------------------------------------------------------
67 ModuleList (const ModuleList& rhs);
69 ModuleList (ModuleList::Notifier* notifier);
71 //------------------------------------------------------------------
73 //------------------------------------------------------------------
76 //------------------------------------------------------------------
77 /// Assignment operator.
79 /// Copies the module list from \a rhs into this list.
82 /// Another module list object.
85 /// A const reference to this object.
86 //------------------------------------------------------------------
88 operator= (const ModuleList& rhs);
90 //------------------------------------------------------------------
91 /// Append a module to the module list.
93 /// Appends the module to the collection.
95 /// @param[in] module_sp
96 /// A shared pointer to a module to add to this collection.
97 //------------------------------------------------------------------
99 Append (const lldb::ModuleSP &module_sp);
101 //------------------------------------------------------------------
102 /// Append a module to the module list and remove any equivalent
103 /// modules. Equivalent modules are ones whose file, platform file
104 /// and architecture matches.
106 /// Replaces the module to the collection.
108 /// @param[in] module_sp
109 /// A shared pointer to a module to replace in this collection.
110 //------------------------------------------------------------------
112 ReplaceEquivalent (const lldb::ModuleSP &module_sp);
115 AppendIfNeeded (const lldb::ModuleSP &module_sp);
118 Append (const ModuleList& module_list);
121 AppendIfNeeded (const ModuleList& module_list);
124 ReplaceModule (const lldb::ModuleSP &old_module_sp, const lldb::ModuleSP &new_module_sp);
126 //------------------------------------------------------------------
127 /// Clear the object's state.
129 /// Clears the list of modules and releases a reference to each
130 /// module object and if the reference count goes to zero, the
131 /// module will be deleted.
132 //------------------------------------------------------------------
136 //------------------------------------------------------------------
137 /// Clear the object's state.
139 /// Clears the list of modules and releases a reference to each
140 /// module object and if the reference count goes to zero, the
141 /// module will be deleted. Also release all memory that might be
142 /// held by any collection classes (like std::vector)
143 //------------------------------------------------------------------
146 //------------------------------------------------------------------
147 /// Dump the description of each module contained in this list.
149 /// Dump the description of each module contained in this list to
150 /// the supplied stream \a s.
153 /// The stream to which to dump the object description.
155 /// @see Module::Dump(Stream *) const
156 //------------------------------------------------------------------
158 Dump (Stream *s) const;
161 LogUUIDAndPaths (Log *log, const char *prefix_cstr);
166 return m_modules_mutex;
170 GetIndexForModule (const Module *module) const;
172 //------------------------------------------------------------------
173 /// Get the module shared pointer for the module at index \a idx.
176 /// An index into this module collection.
179 /// A shared pointer to a Module which can contain NULL if
180 /// \a idx is out of range.
182 /// @see ModuleList::GetSize()
183 //------------------------------------------------------------------
185 GetModuleAtIndex (size_t idx) const;
187 //------------------------------------------------------------------
188 /// Get the module shared pointer for the module at index \a idx without
189 /// acquiring the ModuleList mutex. This MUST already have been
190 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
193 /// An index into this module collection.
196 /// A shared pointer to a Module which can contain NULL if
197 /// \a idx is out of range.
199 /// @see ModuleList::GetSize()
200 //------------------------------------------------------------------
202 GetModuleAtIndexUnlocked (size_t idx) const;
204 //------------------------------------------------------------------
205 /// Get the module pointer for the module at index \a idx.
208 /// An index into this module collection.
211 /// A pointer to a Module which can by NULL if \a idx is out
214 /// @see ModuleList::GetSize()
215 //------------------------------------------------------------------
217 GetModulePointerAtIndex (size_t idx) const;
219 //------------------------------------------------------------------
220 /// Get the module pointer for the module at index \a idx without
221 /// acquiring the ModuleList mutex. This MUST already have been
222 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
225 /// An index into this module collection.
228 /// A pointer to a Module which can by NULL if \a idx is out
231 /// @see ModuleList::GetSize()
232 //------------------------------------------------------------------
234 GetModulePointerAtIndexUnlocked (size_t idx) const;
236 //------------------------------------------------------------------
237 /// Find compile units by partial or full path.
239 /// Finds all compile units that match \a path in all of the modules
240 /// and returns the results in \a sc_list.
243 /// The name of the compile unit we are looking for.
245 /// @param[in] append
246 /// If \b true, then append any compile units that were found
247 /// to \a sc_list. If \b false, then the \a sc_list is cleared
248 /// and the contents of \a sc_list are replaced.
250 /// @param[out] sc_list
251 /// A symbol context list that gets filled in with all of the
255 /// The number of matches added to \a sc_list.
256 //------------------------------------------------------------------
258 FindCompileUnits (const FileSpec &path,
260 SymbolContextList &sc_list) const;
262 //------------------------------------------------------------------
263 /// @see Module::FindFunctions ()
264 //------------------------------------------------------------------
266 FindFunctions (const ConstString &name,
267 uint32_t name_type_mask,
268 bool include_symbols,
269 bool include_inlines,
271 SymbolContextList &sc_list) const;
273 //------------------------------------------------------------------
274 /// @see Module::FindFunctionSymbols ()
275 //------------------------------------------------------------------
277 FindFunctionSymbols (const ConstString &name,
278 uint32_t name_type_mask,
279 SymbolContextList& sc_list);
281 //------------------------------------------------------------------
282 /// Find global and static variables by name.
285 /// The name of the global or static variable we are looking
288 /// @param[in] append
289 /// If \b true, any matches will be appended to \a
290 /// variable_list, else matches replace the contents of
291 /// \a variable_list.
293 /// @param[in] max_matches
294 /// Allow the number of matches to be limited to \a
295 /// max_matches. Specify UINT32_MAX to get all possible matches.
297 /// @param[in] variable_list
298 /// A list of variables that gets the matches appended to (if
299 /// \a append it \b true), or replace (if \a append is \b false).
302 /// The number of matches added to \a variable_list.
303 //------------------------------------------------------------------
305 FindGlobalVariables (const ConstString &name,
308 VariableList& variable_list) const;
310 //------------------------------------------------------------------
311 /// Find global and static variables by regular expression.
314 /// A regular expression to use when matching the name.
316 /// @param[in] append
317 /// If \b true, any matches will be appended to \a
318 /// variable_list, else matches replace the contents of
319 /// \a variable_list.
321 /// @param[in] max_matches
322 /// Allow the number of matches to be limited to \a
323 /// max_matches. Specify UINT32_MAX to get all possible matches.
325 /// @param[in] variable_list
326 /// A list of variables that gets the matches appended to (if
327 /// \a append it \b true), or replace (if \a append is \b false).
330 /// The number of matches added to \a variable_list.
331 //------------------------------------------------------------------
333 FindGlobalVariables (const RegularExpression& regex,
336 VariableList& variable_list) const;
338 //------------------------------------------------------------------
339 /// Finds the first module whose file specification matches \a
342 /// @param[in] file_spec_ptr
343 /// A file specification object to match against the Module's
344 /// file specifications. If \a file_spec does not have
345 /// directory information, matches will occur by matching only
346 /// the basename of any modules in this list. If this value is
347 /// NULL, then file specifications won't be compared when
348 /// searching for matching modules.
350 /// @param[in] arch_ptr
351 /// The architecture to search for if non-NULL. If this value
352 /// is NULL no architecture matching will be performed.
354 /// @param[in] uuid_ptr
355 /// The uuid to search for if non-NULL. If this value is NULL
356 /// no uuid matching will be performed.
358 /// @param[in] object_name
359 /// An optional object name that must match as well. This value
362 /// @param[out] matching_module_list
363 /// A module list that gets filled in with any modules that
364 /// match the search criteria.
367 /// The number of matching modules found by the search.
368 //------------------------------------------------------------------
370 FindModules (const ModuleSpec &module_spec,
371 ModuleList& matching_module_list) const;
374 FindModule (const Module *module_ptr) const;
376 //------------------------------------------------------------------
377 // Find a module by UUID
379 // The UUID value for a module is extracted from the ObjectFile and
380 // is the MD5 checksum, or a smarter object file equivalent, so
381 // finding modules by UUID values is very efficient and accurate.
382 //------------------------------------------------------------------
384 FindModule (const UUID &uuid) const;
387 FindFirstModule (const ModuleSpec &module_spec) const;
390 FindSymbolsWithNameAndType (const ConstString &name,
391 lldb::SymbolType symbol_type,
392 SymbolContextList &sc_list,
393 bool append = false) const;
396 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex,
397 lldb::SymbolType symbol_type,
398 SymbolContextList &sc_list,
399 bool append = false) const;
401 //------------------------------------------------------------------
402 /// Find types by name.
405 /// A symbol context that scopes where to extract a type list
409 /// The name of the type we are looking for.
411 /// @param[in] append
412 /// If \b true, any matches will be appended to \a
413 /// variable_list, else matches replace the contents of
414 /// \a variable_list.
416 /// @param[in] max_matches
417 /// Allow the number of matches to be limited to \a
418 /// max_matches. Specify UINT32_MAX to get all possible matches.
420 /// @param[in] encoding
421 /// Limit the search to specific types, or get all types if
422 /// set to Type::invalid.
424 /// @param[in] udt_name
425 /// If the encoding is a user defined type, specify the name
426 /// of the user defined type ("struct", "union", "class", etc).
428 /// @param[out] type_list
429 /// A type list gets populated with any matches.
432 /// The number of matches added to \a type_list.
433 //------------------------------------------------------------------
435 FindTypes (const SymbolContext& sc,
436 const ConstString &name,
437 bool name_is_fully_qualified,
439 TypeList& types) const;
442 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
445 //------------------------------------------------------------------
446 /// Find addresses by file/line
448 /// @param[in] target_sp
449 /// The target the addresses are desired for.
452 /// Source file to locate.
455 /// Source line to locate.
457 /// @param[in] function
458 /// Optional filter function. Addresses within this function will be
459 /// added to the 'local' list. All others will be added to the 'extern' list.
461 /// @param[out] output_local
462 /// All matching addresses within 'function'
464 /// @param[out] output_extern
465 /// All matching addresses not within 'function'
466 void FindAddressesForLine (const lldb::TargetSP target_sp,
467 const FileSpec &file, uint32_t line,
469 std::vector<Address> &output_local, std::vector<Address> &output_extern);
473 Remove (const lldb::ModuleSP &module_sp);
476 Remove (ModuleList &module_list);
479 RemoveIfOrphaned (const Module *module_ptr);
482 RemoveOrphans (bool mandatory);
485 ResolveFileAddress (lldb::addr_t vm_addr,
486 Address& so_addr) const;
488 //------------------------------------------------------------------
489 /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
490 //------------------------------------------------------------------
492 ResolveSymbolContextForAddress (const Address& so_addr,
493 uint32_t resolve_scope,
494 SymbolContext& sc) const;
496 //------------------------------------------------------------------
497 /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
498 //------------------------------------------------------------------
500 ResolveSymbolContextForFilePath (const char *file_path,
503 uint32_t resolve_scope,
504 SymbolContextList& sc_list) const;
506 //------------------------------------------------------------------
507 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
508 //------------------------------------------------------------------
510 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
513 uint32_t resolve_scope,
514 SymbolContextList& sc_list) const;
516 //------------------------------------------------------------------
517 /// Gets the size of the module list.
520 /// The number of modules in the module list.
521 //------------------------------------------------------------------
526 LoadScriptingResourcesInTarget (Target *target,
527 std::list<Error>& errors,
528 Stream* feedback_stream = NULL,
529 bool continue_on_error = true);
532 ModuleIsInCache (const Module *module_ptr);
535 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);
543 RemoveSharedModule (lldb::ModuleSP &module_sp);
546 FindSharedModules (const ModuleSpec &module_spec,
547 ModuleList &matching_module_list);
550 RemoveOrphanSharedModules (bool mandatory);
553 RemoveSharedModuleIfOrphaned (const Module *module_ptr);
556 //------------------------------------------------------------------
558 //------------------------------------------------------------------
559 typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
562 AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
565 RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
568 RemoveImpl (collection::iterator pos, bool use_notifier = true);
571 ClearImpl (bool use_notifier = true);
573 //------------------------------------------------------------------
575 //------------------------------------------------------------------
576 collection m_modules; ///< The collection of modules.
577 mutable Mutex m_modules_mutex;
579 Notifier* m_notifier;
582 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterable;
586 return ModuleIterable(m_modules, GetMutex());
591 } // namespace lldb_private
593 #endif // liblldb_ModuleList_h_