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 /// @see Module::FindFunctions ()
283 //------------------------------------------------------------------
285 FindFunctions(const RegularExpression &name,
286 bool include_symbols,
287 bool include_inlines,
289 SymbolContextList& sc_list);
291 //------------------------------------------------------------------
292 /// Find global and static variables by name.
295 /// The name of the global or static variable we are looking
298 /// @param[in] append
299 /// If \b true, any matches will be appended to \a
300 /// variable_list, else matches replace the contents of
301 /// \a variable_list.
303 /// @param[in] max_matches
304 /// Allow the number of matches to be limited to \a
305 /// max_matches. Specify UINT32_MAX to get all possible matches.
307 /// @param[in] variable_list
308 /// A list of variables that gets the matches appended to (if
309 /// \a append it \b true), or replace (if \a append is \b false).
312 /// The number of matches added to \a variable_list.
313 //------------------------------------------------------------------
315 FindGlobalVariables (const ConstString &name,
318 VariableList& variable_list) const;
320 //------------------------------------------------------------------
321 /// Find global and static variables by regular expression.
324 /// A regular expression to use when matching the name.
326 /// @param[in] append
327 /// If \b true, any matches will be appended to \a
328 /// variable_list, else matches replace the contents of
329 /// \a variable_list.
331 /// @param[in] max_matches
332 /// Allow the number of matches to be limited to \a
333 /// max_matches. Specify UINT32_MAX to get all possible matches.
335 /// @param[in] variable_list
336 /// A list of variables that gets the matches appended to (if
337 /// \a append it \b true), or replace (if \a append is \b false).
340 /// The number of matches added to \a variable_list.
341 //------------------------------------------------------------------
343 FindGlobalVariables (const RegularExpression& regex,
346 VariableList& variable_list) const;
348 //------------------------------------------------------------------
349 /// Finds the first module whose file specification matches \a
352 /// @param[in] file_spec_ptr
353 /// A file specification object to match against the Module's
354 /// file specifications. If \a file_spec does not have
355 /// directory information, matches will occur by matching only
356 /// the basename of any modules in this list. If this value is
357 /// NULL, then file specifications won't be compared when
358 /// searching for matching modules.
360 /// @param[in] arch_ptr
361 /// The architecture to search for if non-NULL. If this value
362 /// is NULL no architecture matching will be performed.
364 /// @param[in] uuid_ptr
365 /// The uuid to search for if non-NULL. If this value is NULL
366 /// no uuid matching will be performed.
368 /// @param[in] object_name
369 /// An optional object name that must match as well. This value
372 /// @param[out] matching_module_list
373 /// A module list that gets filled in with any modules that
374 /// match the search criteria.
377 /// The number of matching modules found by the search.
378 //------------------------------------------------------------------
380 FindModules (const ModuleSpec &module_spec,
381 ModuleList& matching_module_list) const;
384 FindModule (const Module *module_ptr) const;
386 //------------------------------------------------------------------
387 // Find a module by UUID
389 // The UUID value for a module is extracted from the ObjectFile and
390 // is the MD5 checksum, or a smarter object file equivalent, so
391 // finding modules by UUID values is very efficient and accurate.
392 //------------------------------------------------------------------
394 FindModule (const UUID &uuid) const;
397 FindFirstModule (const ModuleSpec &module_spec) const;
400 FindSymbolsWithNameAndType (const ConstString &name,
401 lldb::SymbolType symbol_type,
402 SymbolContextList &sc_list,
403 bool append = false) const;
406 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex,
407 lldb::SymbolType symbol_type,
408 SymbolContextList &sc_list,
409 bool append = false) const;
411 //------------------------------------------------------------------
412 /// Find types by name.
415 /// A symbol context that scopes where to extract a type list
419 /// The name of the type we are looking for.
421 /// @param[in] append
422 /// If \b true, any matches will be appended to \a
423 /// variable_list, else matches replace the contents of
424 /// \a variable_list.
426 /// @param[in] max_matches
427 /// Allow the number of matches to be limited to \a
428 /// max_matches. Specify UINT32_MAX to get all possible matches.
430 /// @param[in] encoding
431 /// Limit the search to specific types, or get all types if
432 /// set to Type::invalid.
434 /// @param[in] udt_name
435 /// If the encoding is a user defined type, specify the name
436 /// of the user defined type ("struct", "union", "class", etc).
438 /// @param[out] type_list
439 /// A type list gets populated with any matches.
442 /// The number of matches added to \a type_list.
443 //------------------------------------------------------------------
445 FindTypes (const SymbolContext& sc,
446 const ConstString &name,
447 bool name_is_fully_qualified,
449 TypeList& types) const;
452 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' list.
471 /// @param[out] output_local
472 /// All matching addresses within 'function'
474 /// @param[out] output_extern
475 /// All matching addresses not within 'function'
476 void FindAddressesForLine (const lldb::TargetSP target_sp,
477 const FileSpec &file, uint32_t line,
479 std::vector<Address> &output_local, std::vector<Address> &output_extern);
483 Remove (const lldb::ModuleSP &module_sp);
486 Remove (ModuleList &module_list);
489 RemoveIfOrphaned (const Module *module_ptr);
492 RemoveOrphans (bool mandatory);
495 ResolveFileAddress (lldb::addr_t vm_addr,
496 Address& so_addr) const;
498 //------------------------------------------------------------------
499 /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
500 //------------------------------------------------------------------
502 ResolveSymbolContextForAddress (const Address& so_addr,
503 uint32_t resolve_scope,
504 SymbolContext& sc) const;
506 //------------------------------------------------------------------
507 /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
508 //------------------------------------------------------------------
510 ResolveSymbolContextForFilePath (const char *file_path,
513 uint32_t resolve_scope,
514 SymbolContextList& sc_list) const;
516 //------------------------------------------------------------------
517 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
518 //------------------------------------------------------------------
520 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
523 uint32_t resolve_scope,
524 SymbolContextList& sc_list) const;
526 //------------------------------------------------------------------
527 /// Gets the size of the module list.
530 /// The number of modules in the module list.
531 //------------------------------------------------------------------
536 LoadScriptingResourcesInTarget (Target *target,
537 std::list<Error>& errors,
538 Stream* feedback_stream = NULL,
539 bool continue_on_error = true);
542 ModuleIsInCache (const Module *module_ptr);
545 GetSharedModule (const ModuleSpec &module_spec,
546 lldb::ModuleSP &module_sp,
547 const FileSpecList *module_search_paths_ptr,
548 lldb::ModuleSP *old_module_sp_ptr,
549 bool *did_create_ptr,
550 bool always_create = false);
553 RemoveSharedModule (lldb::ModuleSP &module_sp);
556 FindSharedModules (const ModuleSpec &module_spec,
557 ModuleList &matching_module_list);
560 RemoveOrphanSharedModules (bool mandatory);
563 RemoveSharedModuleIfOrphaned (const Module *module_ptr);
566 //------------------------------------------------------------------
568 //------------------------------------------------------------------
569 typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
572 AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
575 RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
578 RemoveImpl (collection::iterator pos, bool use_notifier = true);
581 ClearImpl (bool use_notifier = true);
583 //------------------------------------------------------------------
585 //------------------------------------------------------------------
586 collection m_modules; ///< The collection of modules.
587 mutable Mutex m_modules_mutex;
589 Notifier* m_notifier;
592 typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterable;
596 return ModuleIterable(m_modules, GetMutex());
599 typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterableNoLocking;
600 ModuleIterableNoLocking
603 return ModuleIterableNoLocking(m_modules);
608 } // namespace lldb_private
610 #endif // liblldb_ModuleList_h_