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 Remove (const lldb::ModuleSP &module_sp);
447 Remove (ModuleList &module_list);
450 RemoveIfOrphaned (const Module *module_ptr);
453 RemoveOrphans (bool mandatory);
456 ResolveFileAddress (lldb::addr_t vm_addr,
457 Address& so_addr) const;
459 //------------------------------------------------------------------
460 /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
461 //------------------------------------------------------------------
463 ResolveSymbolContextForAddress (const Address& so_addr,
464 uint32_t resolve_scope,
465 SymbolContext& sc) const;
467 //------------------------------------------------------------------
468 /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
469 //------------------------------------------------------------------
471 ResolveSymbolContextForFilePath (const char *file_path,
474 uint32_t resolve_scope,
475 SymbolContextList& sc_list) const;
477 //------------------------------------------------------------------
478 /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
479 //------------------------------------------------------------------
481 ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
484 uint32_t resolve_scope,
485 SymbolContextList& sc_list) const;
487 //------------------------------------------------------------------
488 /// Gets the size of the module list.
491 /// The number of modules in the module list.
492 //------------------------------------------------------------------
497 LoadScriptingResourcesInTarget (Target *target,
498 std::list<Error>& errors,
499 Stream* feedback_stream = NULL,
500 bool continue_on_error = true);
503 ModuleIsInCache (const Module *module_ptr);
506 GetSharedModule (const ModuleSpec &module_spec,
507 lldb::ModuleSP &module_sp,
508 const FileSpecList *module_search_paths_ptr,
509 lldb::ModuleSP *old_module_sp_ptr,
510 bool *did_create_ptr,
511 bool always_create = false);
514 RemoveSharedModule (lldb::ModuleSP &module_sp);
517 FindSharedModules (const ModuleSpec &module_spec,
518 ModuleList &matching_module_list);
521 RemoveOrphanSharedModules (bool mandatory);
524 RemoveSharedModuleIfOrphaned (const Module *module_ptr);
527 //------------------------------------------------------------------
529 //------------------------------------------------------------------
530 typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
533 AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
536 RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
539 RemoveImpl (collection::iterator pos, bool use_notifier = true);
542 ClearImpl (bool use_notifier = true);
544 //------------------------------------------------------------------
546 //------------------------------------------------------------------
547 collection m_modules; ///< The collection of modules.
548 mutable Mutex m_modules_mutex;
550 Notifier* m_notifier;
554 } // namespace lldb_private
556 #endif // liblldb_ModuleList_h_