contrib/llvm/tools/lldb/include/lldb/Core/ModuleList.h

   1 //===-- ModuleList.h --------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_ModuleList_h_
  11 #define liblldb_ModuleList_h_
  12
  13 #include <vector>
  14 #include <list>
  15
  16 #include "lldb/lldb-private.h"
  17 #include "lldb/Host/Mutex.h"
  18
  19 namespace lldb_private {
  20
  21 //----------------------------------------------------------------------
  22 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
  23 /// @brief A collection class for Module objects.
  24 ///
  25 /// Modules in the module collection class are stored as reference
  26 /// counted shared pointers to Module objects.
  27 //----------------------------------------------------------------------
  28 class ModuleList
  29 {
  30 public:
  31
  32     class Notifier
  33     {
  34     public:
  35         virtual void
  36         ModuleAdded (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
  37         virtual void
  38         ModuleRemoved (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
  39         virtual void
  40         ModuleUpdated (const ModuleList& module_list, const lldb::ModuleSP& old_module_sp,
  41                        const lldb::ModuleSP& new_module_sp) = 0;
  42         virtual void
  43         WillClearList (const ModuleList& module_list) = 0;
  44
  45         virtual
  46         ~Notifier ()
  47         {}
  48     };
  49
  50     //------------------------------------------------------------------
  51     /// Default constructor.
  52     ///
  53     /// Creates an empty list of Module objects.
  54     //------------------------------------------------------------------
  55     ModuleList ();
  56
  57     //------------------------------------------------------------------
  58     /// Copy Constructor.
  59     ///
  60     /// Creates a new module list object with a copy of the modules from
  61     /// \a rhs.
  62     ///
  63     /// @param[in] rhs
  64     ///     Another module list object.
  65     //------------------------------------------------------------------
  66     ModuleList (const ModuleList& rhs);
  67
  68     ModuleList (ModuleList::Notifier* notifier);
  69
  70     //------------------------------------------------------------------
  71     /// Destructor.
  72     //------------------------------------------------------------------
  73     ~ModuleList ();
  74
  75     //------------------------------------------------------------------
  76     /// Assignment operator.
  77     ///
  78     /// Copies the module list from \a rhs into this list.
  79     ///
  80     /// @param[in] rhs
  81     ///     Another module list object.
  82     ///
  83     /// @return
  84     ///     A const reference to this object.
  85     //------------------------------------------------------------------
  86     const ModuleList&
  87     operator= (const ModuleList& rhs);
  88
  89     //------------------------------------------------------------------
  90     /// Append a module to the module list.
  91     ///
  92     /// Appends the module to the collection.
  93     ///
  94     /// @param[in] module_sp
  95     ///     A shared pointer to a module to add to this collection.
  96     //------------------------------------------------------------------
  97     void
  98     Append (const lldb::ModuleSP &module_sp);
  99
 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.
 104     ///
 105     /// Replaces the module to the collection.
 106     ///
 107     /// @param[in] module_sp
 108     ///     A shared pointer to a module to replace in this collection.
 109     //------------------------------------------------------------------
 110     void
 111     ReplaceEquivalent (const lldb::ModuleSP &module_sp);
 112
 113     bool
 114     AppendIfNeeded (const lldb::ModuleSP &module_sp);
 115
 116     void
 117     Append (const ModuleList& module_list);
 118
 119     bool
 120     AppendIfNeeded (const ModuleList& module_list);
 121
 122     bool
 123     ReplaceModule (const lldb::ModuleSP &old_module_sp, const lldb::ModuleSP &new_module_sp);
 124
 125     //------------------------------------------------------------------
 126     /// Clear the object's state.
 127     ///
 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     //------------------------------------------------------------------
 132     void
 133     Clear ();
 134
 135     //------------------------------------------------------------------
 136     /// Clear the object's state.
 137     ///
 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     //------------------------------------------------------------------
 143     void
 144     Destroy();
 145     //------------------------------------------------------------------
 146     /// Dump the description of each module contained in this list.
 147     ///
 148     /// Dump the description of each module contained in this list to
 149     /// the supplied stream \a s.
 150     ///
 151     /// @param[in] s
 152     ///     The stream to which to dump the object descripton.
 153     ///
 154     /// @see Module::Dump(Stream *) const
 155     //------------------------------------------------------------------
 156     void
 157     Dump (Stream *s) const;
 158
 159     void
 160     LogUUIDAndPaths (Log *log, const char *prefix_cstr);
 161
 162     Mutex &
 163     GetMutex () const
 164     {
 165         return m_modules_mutex;
 166     }
 167
 168     size_t
 169     GetIndexForModule (const Module *module) const;
 170
 171     //------------------------------------------------------------------
 172     /// Get the module shared pointer for the module at index \a idx.
 173     ///
 174     /// @param[in] idx
 175     ///     An index into this module collection.
 176     ///
 177     /// @return
 178     ///     A shared pointer to a Module which can contain NULL if
 179     ///     \a idx is out of range.
 180     ///
 181     /// @see ModuleList::GetSize()
 182     //------------------------------------------------------------------
 183     lldb::ModuleSP
 184     GetModuleAtIndex (size_t idx) const;
 185
 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.
 190     ///
 191     /// @param[in] idx
 192     ///     An index into this module collection.
 193     ///
 194     /// @return
 195     ///     A shared pointer to a Module which can contain NULL if
 196     ///     \a idx is out of range.
 197     ///
 198     /// @see ModuleList::GetSize()
 199     //------------------------------------------------------------------
 200     lldb::ModuleSP
 201     GetModuleAtIndexUnlocked (size_t idx) const;
 202
 203     //------------------------------------------------------------------
 204     /// Get the module pointer for the module at index \a idx.
 205     ///
 206     /// @param[in] idx
 207     ///     An index into this module collection.
 208     ///
 209     /// @return
 210     ///     A pointer to a Module which can by NULL if \a idx is out
 211     ///     of range.
 212     ///
 213     /// @see ModuleList::GetSize()
 214     //------------------------------------------------------------------
 215     Module*
 216     GetModulePointerAtIndex (size_t idx) const;
 217
 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.
 222     ///
 223     /// @param[in] idx
 224     ///     An index into this module collection.
 225     ///
 226     /// @return
 227     ///     A pointer to a Module which can by NULL if \a idx is out
 228     ///     of range.
 229     ///
 230     /// @see ModuleList::GetSize()
 231     //------------------------------------------------------------------
 232     Module*
 233     GetModulePointerAtIndexUnlocked (size_t idx) const;
 234
 235     //------------------------------------------------------------------
 236     /// Find compile units by partial or full path.
 237     ///
 238     /// Finds all compile units that match \a path in all of the modules
 239     /// and returns the results in \a sc_list.
 240     ///
 241     /// @param[in] path
 242     ///     The name of the compile unit we are looking for.
 243     ///
 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.
 248     ///
 249     /// @param[out] sc_list
 250     ///     A symbol context list that gets filled in with all of the
 251     ///     matches.
 252     ///
 253     /// @return
 254     ///     The number of matches added to \a sc_list.
 255     //------------------------------------------------------------------
 256     size_t
 257     FindCompileUnits (const FileSpec &path,
 258                       bool append,
 259                       SymbolContextList &sc_list) const;
 260
 261     //------------------------------------------------------------------
 262     /// @see Module::FindFunctions ()
 263     //------------------------------------------------------------------
 264     size_t
 265     FindFunctions (const ConstString &name,
 266                    uint32_t name_type_mask,
 267                    bool include_symbols,
 268                    bool include_inlines,
 269                    bool append,
 270                    SymbolContextList &sc_list) const;
 271
 272     //------------------------------------------------------------------
 273     /// @see Module::FindFunctionSymbols ()
 274     //------------------------------------------------------------------
 275     size_t
 276     FindFunctionSymbols (const ConstString &name,
 277                          uint32_t name_type_mask,
 278                          SymbolContextList& sc_list);
 279
 280     //------------------------------------------------------------------
 281     /// Find global and static variables by name.
 282     ///
 283     /// @param[in] name
 284     ///     The name of the global or static variable we are looking
 285     ///     for.
 286     ///
 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.
 291     ///
 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.
 295     ///
 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).
 299     ///
 300     /// @return
 301     ///     The number of matches added to \a variable_list.
 302     //------------------------------------------------------------------
 303     size_t
 304     FindGlobalVariables (const ConstString &name,
 305                          bool append,
 306                          size_t max_matches,
 307                          VariableList& variable_list) const;
 308
 309     //------------------------------------------------------------------
 310     /// Find global and static variables by regular exression.
 311     ///
 312     /// @param[in] regex
 313     ///     A regular expression to use when matching the name.
 314     ///
 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.
 319     ///
 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.
 323     ///
 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).
 327     ///
 328     /// @return
 329     ///     The number of matches added to \a variable_list.
 330     //------------------------------------------------------------------
 331     size_t
 332     FindGlobalVariables (const RegularExpression& regex,
 333                          bool append,
 334                          size_t max_matches,
 335                          VariableList& variable_list) const;
 336
 337     //------------------------------------------------------------------
 338     /// Finds the first module whose file specification matches \a
 339     /// file_spec.
 340     ///
 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.
 348     ///
 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.
 352     ///
 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.
 356     ///
 357     /// @param[in] object_name
 358     ///     An optional object name that must match as well. This value
 359     ///     can be NULL.
 360     ///
 361     /// @param[out] matching_module_list
 362     ///     A module list that gets filled in with any modules that
 363     ///     match the search criteria.
 364     ///
 365     /// @return
 366     ///     The number of matching modules found by the search.
 367     //------------------------------------------------------------------
 368     size_t
 369     FindModules (const ModuleSpec &module_spec,
 370                  ModuleList& matching_module_list) const;
 371
 372     lldb::ModuleSP
 373     FindModule (const Module *module_ptr) const;
 374
 375     //------------------------------------------------------------------
 376     // Find a module by UUID
 377     //
 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     //------------------------------------------------------------------
 382     lldb::ModuleSP
 383     FindModule (const UUID &uuid) const;
 384
 385     lldb::ModuleSP
 386     FindFirstModule (const ModuleSpec &module_spec) const;
 387
 388     size_t
 389     FindSymbolsWithNameAndType (const ConstString &name,
 390                                 lldb::SymbolType symbol_type,
 391                                 SymbolContextList &sc_list,
 392                                 bool append = false) const;
 393
 394     size_t
 395     FindSymbolsMatchingRegExAndType (const RegularExpression &regex,
 396                                      lldb::SymbolType symbol_type,
 397                                      SymbolContextList &sc_list,
 398                                      bool append = false) const;
 399
 400     //------------------------------------------------------------------
 401     /// Find types by name.
 402     ///
 403     /// @param[in] sc
 404     ///     A symbol context that scopes where to extract a type list
 405     ///     from.
 406     ///
 407     /// @param[in] name
 408     ///     The name of the type we are looking for.
 409     ///
 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.
 414     ///
 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.
 418     ///
 419     /// @param[in] encoding
 420     ///     Limit the search to specific types, or get all types if
 421     ///     set to Type::invalid.
 422     ///
 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).
 426     ///
 427     /// @param[out] type_list
 428     ///     A type list gets populated with any matches.
 429     ///
 430     /// @return
 431     ///     The number of matches added to \a type_list.
 432     //------------------------------------------------------------------
 433     size_t
 434     FindTypes (const SymbolContext& sc,
 435                const ConstString &name,
 436                bool name_is_fully_qualified,
 437                size_t max_matches,
 438                TypeList& types) const;
 439
 440     bool
 441     FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
 442
 443
 444     //------------------------------------------------------------------
 445     /// Find addresses by file/line
 446     ///
 447     /// @param[in] target_sp
 448     ///     The target the addresses are desired for.
 449     ///
 450     /// @param[in] file
 451     ///     Source file to locate.
 452     ///
 453     /// @param[in] line
 454     ///     Source line to locate.
 455     ///
 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.
 459     ///
 460     /// @param[out] output_local
 461     ///     All matching addresses within 'function'
 462     ///
 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,
 467                                Function *function,
 468                                std::vector<Address> &output_local, std::vector<Address> &output_extern);
 469
 470
 471     bool
 472     Remove (const lldb::ModuleSP &module_sp);
 473
 474     size_t
 475     Remove (ModuleList &module_list);
 476
 477     bool
 478     RemoveIfOrphaned (const Module *module_ptr);
 479
 480     size_t
 481     RemoveOrphans (bool mandatory);
 482
 483     bool
 484     ResolveFileAddress (lldb::addr_t vm_addr,
 485                         Address& so_addr) const;
 486
 487     //------------------------------------------------------------------
 488     /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
 489     //------------------------------------------------------------------
 490     uint32_t
 491     ResolveSymbolContextForAddress (const Address& so_addr,
 492                                     uint32_t resolve_scope,
 493                                     SymbolContext& sc) const;
 494
 495     //------------------------------------------------------------------
 496     /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
 497     //------------------------------------------------------------------
 498     uint32_t
 499     ResolveSymbolContextForFilePath (const char *file_path,
 500                                      uint32_t line,
 501                                      bool check_inlines,
 502                                      uint32_t resolve_scope,
 503                                      SymbolContextList& sc_list) const;
 504
 505     //------------------------------------------------------------------
 506     /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
 507     //------------------------------------------------------------------
 508     uint32_t
 509     ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
 510                                      uint32_t line,
 511                                      bool check_inlines,
 512                                      uint32_t resolve_scope,
 513                                      SymbolContextList& sc_list) const;
 514
 515     //------------------------------------------------------------------
 516     /// Gets the size of the module list.
 517     ///
 518     /// @return
 519     ///     The number of modules in the module list.
 520     //------------------------------------------------------------------
 521     size_t
 522     GetSize () const;
 523
 524     bool
 525     LoadScriptingResourcesInTarget (Target *target,
 526                                     std::list<Error>& errors,
 527                                     Stream* feedback_stream = NULL,
 528                                     bool continue_on_error = true);
 529
 530     static bool
 531     ModuleIsInCache (const Module *module_ptr);
 532
 533     static Error
 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);
 540
 541     static bool
 542     RemoveSharedModule (lldb::ModuleSP &module_sp);
 543
 544     static size_t
 545     FindSharedModules (const ModuleSpec &module_spec,
 546                        ModuleList &matching_module_list);
 547
 548     static size_t
 549     RemoveOrphanSharedModules (bool mandatory);
 550
 551     static bool
 552     RemoveSharedModuleIfOrphaned (const Module *module_ptr);
 553
 554 protected:
 555     //------------------------------------------------------------------
 556     // Class typedefs.
 557     //------------------------------------------------------------------
 558     typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
 559
 560     void
 561     AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 562
 563     bool
 564     RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 565
 566     collection::iterator
 567     RemoveImpl (collection::iterator pos, bool use_notifier = true);
 568
 569     void
 570     ClearImpl (bool use_notifier = true);
 571
 572     //------------------------------------------------------------------
 573     // Member variables.
 574     //------------------------------------------------------------------
 575     collection m_modules; ///< The collection of modules.
 576     mutable Mutex m_modules_mutex;
 577
 578     Notifier* m_notifier;
 579
 580 };
 581
 582 } // namespace lldb_private
 583
 584 #endif  // liblldb_ModuleList_h_