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"
19 namespace lldb_private {
21 //----------------------------------------------------------------------
22 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
23 /// @brief A collection class for Module objects.
25 /// Modules in the module collection class are stored as reference
26 /// counted shared pointers to Module objects.
27 //----------------------------------------------------------------------
36 ModuleAdded (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
38 ModuleRemoved (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
40 ModuleUpdated (const ModuleList& module_list, const lldb::ModuleSP& old_module_sp,
41 const lldb::ModuleSP& new_module_sp) = 0;
43 WillClearList (const ModuleList& module_list) = 0;
50 //------------------------------------------------------------------
51 /// Default constructor.
53 /// Creates an empty list of Module objects.
54 //------------------------------------------------------------------
57 //------------------------------------------------------------------
60 /// Creates a new module list object with a copy of the modules from
64 /// Another module list object.
65 //------------------------------------------------------------------
66 ModuleList (const ModuleList& rhs);
68 ModuleList (ModuleList::Notifier* notifier);
70 //------------------------------------------------------------------
72 //------------------------------------------------------------------
75 //------------------------------------------------------------------
76 /// Assignment operator.
78 /// Copies the module list from \a rhs into this list.
81 /// Another module list object.
84 /// A const reference to this object.
85 //------------------------------------------------------------------
87 operator= (const ModuleList& rhs);
89 //------------------------------------------------------------------
90 /// Append a module to the module list.
92 /// Appends the module to the collection.
94 /// @param[in] module_sp
95 /// A shared pointer to a module to add to this collection.
96 //------------------------------------------------------------------
98 Append (const lldb::ModuleSP &module_sp);
100 //------------------------------------------------------------------
101 /// Append a module to the module list and remove any equivalent
102 /// modules. Equivalent modules are ones whose file, platform file
103 /// and architecture matches.
105 /// Replaces the module to the collection.
107 /// @param[in] module_sp
108 /// A shared pointer to a module to replace in this collection.
109 //------------------------------------------------------------------
111 ReplaceEquivalent (const lldb::ModuleSP &module_sp);
114 AppendIfNeeded (const lldb::ModuleSP &module_sp);
117 Append (const ModuleList& module_list);
120 AppendIfNeeded (const ModuleList& module_list);
123 ReplaceModule (const lldb::ModuleSP &old_module_sp, const lldb::ModuleSP &new_module_sp);
125 //------------------------------------------------------------------
126 /// Clear the object's state.
128 /// Clears the list of modules and releases a reference to each
129 /// module object and if the reference count goes to zero, the
130 /// module will be deleted.
131 //------------------------------------------------------------------
135 //------------------------------------------------------------------
136 /// Clear the object's state.
138 /// Clears the list of modules and releases a reference to each
139 /// module object and if the reference count goes to zero, the
140 /// module will be deleted. Also relese all memory that might be
141 /// held by any collection classes (like std::vector)
142 //------------------------------------------------------------------
145 //------------------------------------------------------------------
146 /// Dump the description of each module contained in this list.
148 /// Dump the description of each module contained in this list to
149 /// the supplied stream \a s.
152 /// The stream to which to dump the object descripton.
154 /// @see Module::Dump(Stream *) const
155 //------------------------------------------------------------------
157 Dump (Stream *s) const;
160 LogUUIDAndPaths (Log *log, const char *prefix_cstr);
165 return m_modules_mutex;
169 GetIndexForModule (const Module *module) const;
171 //------------------------------------------------------------------
172 /// Get the module shared pointer for the module at index \a idx.
175 /// An index into this module collection.
178 /// A shared pointer to a Module which can contain NULL if
179 /// \a idx is out of range.
181 /// @see ModuleList::GetSize()
182 //------------------------------------------------------------------
184 GetModuleAtIndex (size_t idx) const;
186 //------------------------------------------------------------------
187 /// Get the module shared pointer for the module at index \a idx without
188 /// acquiring the ModuleList mutex. This MUST already have been
189 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
192 /// An index into this module collection.
195 /// A shared pointer to a Module which can contain NULL if
196 /// \a idx is out of range.
198 /// @see ModuleList::GetSize()
199 //------------------------------------------------------------------
201 GetModuleAtIndexUnlocked (size_t idx) const;
203 //------------------------------------------------------------------
204 /// Get the module pointer for the module at index \a idx.
207 /// An index into this module collection.
210 /// A pointer to a Module which can by NULL if \a idx is out
213 /// @see ModuleList::GetSize()
214 //------------------------------------------------------------------
216 GetModulePointerAtIndex (size_t idx) const;
218 //------------------------------------------------------------------
219 /// Get the module pointer for the module at index \a idx without
220 /// acquiring the ModuleList mutex. This MUST already have been
221 /// acquired with ModuleList::GetMutex and locked for this call to be safe.
224 /// An index into this module collection.
227 /// A pointer to a Module which can by NULL if \a idx is out
230 /// @see ModuleList::GetSize()
231 //------------------------------------------------------------------
233 GetModulePointerAtIndexUnlocked (size_t idx) const;
235 //------------------------------------------------------------------
236 /// Find compile units by partial or full path.
238 /// Finds all compile units that match \a path in all of the modules
239 /// and returns the results in \a sc_list.
242 /// The name of the compile unit we are looking for.
244 /// @param[in] append
245 /// If \b true, then append any compile units that were found
246 /// to \a sc_list. If \b false, then the \a sc_list is cleared
247 /// and the contents of \a sc_list are replaced.
249 /// @param[out] sc_list
250 /// A symbol context list that gets filled in with all of the
254 /// The number of matches added to \a sc_list.
255 //------------------------------------------------------------------
257 FindCompileUnits (const FileSpec &path,
259 SymbolContextList &sc_list) const;
261 //------------------------------------------------------------------
262 /// @see Module::FindFunctions ()
263 //------------------------------------------------------------------
265 FindFunctions (const ConstString &name,
266 uint32_t name_type_mask,
267 bool include_symbols,
268 bool include_inlines,
270 SymbolContextList &sc_list) const;
272 //------------------------------------------------------------------
273 /// @see Module::FindFunctionSymbols ()
274 //------------------------------------------------------------------
276 FindFunctionSymbols (const ConstString &name,
277 uint32_t name_type_mask,
278 SymbolContextList& sc_list);
280 //------------------------------------------------------------------
281 /// Find global and static variables by name.
284 /// The name of the global or static variable we are looking
287 /// @param[in] append
288 /// If \b true, any matches will be appended to \a
289 /// variable_list, else matches replace the contents of
290 /// \a variable_list.
292 /// @param[in] max_matches
293 /// Allow the number of matches to be limited to \a
294 /// max_matches. Specify UINT32_MAX to get all possible matches.
296 /// @param[in] variable_list
297 /// A list of variables that gets the matches appended to (if
298 /// \a append it \b true), or replace (if \a append is \b false).
301 /// The number of matches added to \a variable_list.
302 //------------------------------------------------------------------
304 FindGlobalVariables (const ConstString &name,
307 VariableList& variable_list) const;
309 //------------------------------------------------------------------
310 /// Find global and static variables by regular exression.
313 /// A regular expression to use when matching the name.
315 /// @param[in] append
316 /// If \b true, any matches will be appended to \a
317 /// variable_list, else matches replace the contents of
318 /// \a variable_list.
320 /// @param[in] max_matches
321 /// Allow the number of matches to be limited to \a
322 /// max_matches. Specify UINT32_MAX to get all possible matches.
324 /// @param[in] variable_list
325 /// A list of variables that gets the matches appended to (if
326 /// \a append it \b true), or replace (if \a append is \b false).
329 /// The number of matches added to \a variable_list.
330 //------------------------------------------------------------------
332 FindGlobalVariables (const RegularExpression& regex,
335 VariableList& variable_list) const;
337 //------------------------------------------------------------------
338 /// Finds the first module whose file specification matches \a
341 /// @param[in] file_spec_ptr
342 /// A file specification object to match against the Module's
343 /// file specifications. If \a file_spec does not have
344 /// directory information, matches will occur by matching only
345 /// the basename of any modules in this list. If this value is
346 /// NULL, then file specifications won't be compared when
347 /// searching for matching modules.
349 /// @param[in] arch_ptr
350 /// The architecture to search for if non-NULL. If this value
351 /// is NULL no architecture matching will be performed.
353 /// @param[in] uuid_ptr
354 /// The uuid to search for if non-NULL. If this value is NULL
355 /// no uuid matching will be performed.
357 /// @param[in] object_name
358 /// An optional object name that must match as well. This value
361 /// @param[out] matching_module_list
362 /// A module list that gets filled in with any modules that
363 /// match the search criteria.
366 /// The number of matching modules found by the search.
367 //------------------------------------------------------------------
369 FindModules (const ModuleSpec &module_spec,
370 ModuleList& matching_module_list) const;
373 FindModule (const Module *module_ptr) const;
375 //------------------------------------------------------------------
376 // Find a module by UUID
378 // The UUID value for a module is extracted from the ObjectFile and
379 // is the MD5 checksum, or a smarter object file equivalent, so
380 // finding modules by UUID values is very efficient and accurate.
381 //------------------------------------------------------------------
383 FindModule (const UUID &uuid) const;
386 FindFirstModule (const ModuleSpec &module_spec) const;
389 FindSymbolsWithNameAndType (const ConstString &name,
390 lldb::SymbolType symbol_type,
391 SymbolContextList &sc_list,
392 bool append = false) const;
395 FindSymbolsMatchingRegExAndType (const RegularExpression ®ex,
396 lldb::SymbolType symbol_type,
397 SymbolContextList &sc_list,
398 bool append = false) const;
400 //------------------------------------------------------------------
401 /// Find types by name.
404 /// A symbol context that scopes where to extract a type list
408 /// The name of the type we are looking for.
410 /// @param[in] append
411 /// If \b true, any matches will be appended to \a
412 /// variable_list, else matches replace the contents of
413 /// \a variable_list.
415 /// @param[in] max_matches
416 /// Allow the number of matches to be limited to \a
417 /// max_matches. Specify UINT32_MAX to get all possible matches.
419 /// @param[in] encoding
420 /// Limit the search to specific types, or get all types if
421 /// set to Type::invalid.
423 /// @param[in] udt_name
424 /// If the encoding is a user defined type, specify the name
425 /// of the user defined type ("struct", "union", "class", etc).
427 /// @param[out] type_list
428 /// A type list gets populated with any matches.
431 /// The number of matches added to \a type_list.
432 //------------------------------------------------------------------
434 FindTypes (const SymbolContext& sc,
435 const ConstString &name,
436 bool name_is_fully_qualified,
438 TypeList& types) const;
441 FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
444 //------------------------------------------------------------------
445 /// Find addresses by file/line
447 /// @param[in] target_sp
448 /// The target the addresses are desired for.
451 /// Source file to locate.
454 /// Source line to locate.
456 /// @param[in] function
457 /// Optional filter function. Addresses within this function will be
458 /// added to the 'local' list. All others will be added to the 'extern' list.
460 /// @param[out] output_local
461 /// All matching addresses within 'function'
463 /// @param[out] output_extern
464 /// All matching addresses not within 'function'
465 void FindAddressesForLine (const lldb::TargetSP target_sp,
466 const FileSpec &file, uint32_t line,
468 std::vector<Address> &output_local, std::vector<Address> &output_extern);
472 Remove (const lldb::ModuleSP &module_sp);
475 Remove (ModuleList &module_list);
478 RemoveIfOrphaned (const Module *module_ptr);
481 RemoveOrphans (bool mandatory);
484 ResolveFileAddress (lldb::addr_t vm_addr,
485 Address& so_addr) const;
487 //------------------------------------------------------------------
488 /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
489 //------------------------------------------------------------------
491 ResolveSymbolContextForAddress (const Address& so_addr,
492 uint32_t resolve_scope,
493 SymbolContext& sc) const;
495 //------------------------------------------------------------------
496 /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
497 //------------------------------------------------------------------
499 ResolveSymbolContextForFilePath (const char *file_path,
502 uint32_t resolve_scope,
503 SymbolContextList& sc_list) const;
505 //------------------------------------------------------------------
506 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
507 //------------------------------------------------------------------
509 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
512 uint32_t resolve_scope,
513 SymbolContextList& sc_list) const;
515 //------------------------------------------------------------------
516 /// Gets the size of the module list.
519 /// The number of modules in the module list.
520 //------------------------------------------------------------------
525 LoadScriptingResourcesInTarget (Target *target,
526 std::list<Error>& errors,
527 Stream* feedback_stream = NULL,
528 bool continue_on_error = true);
531 ModuleIsInCache (const Module *module_ptr);
534 GetSharedModule (const ModuleSpec &module_spec,
535 lldb::ModuleSP &module_sp,
536 const FileSpecList *module_search_paths_ptr,
537 lldb::ModuleSP *old_module_sp_ptr,
538 bool *did_create_ptr,
539 bool always_create = false);
542 RemoveSharedModule (lldb::ModuleSP &module_sp);
545 FindSharedModules (const ModuleSpec &module_spec,
546 ModuleList &matching_module_list);
549 RemoveOrphanSharedModules (bool mandatory);
552 RemoveSharedModuleIfOrphaned (const Module *module_ptr);
555 //------------------------------------------------------------------
557 //------------------------------------------------------------------
558 typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
561 AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
564 RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
567 RemoveImpl (collection::iterator pos, bool use_notifier = true);
570 ClearImpl (bool use_notifier = true);
572 //------------------------------------------------------------------
574 //------------------------------------------------------------------
575 collection m_modules; ///< The collection of modules.
576 mutable Mutex m_modules_mutex;
578 Notifier* m_notifier;
582 } // namespace lldb_private
584 #endif // liblldb_ModuleList_h_