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 #include "lldb/Utility/Iterable.h"
  19
  20 namespace lldb_private {
  21
  22 //----------------------------------------------------------------------
  23 /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h"
  24 /// @brief A collection class for Module objects.
  25 ///
  26 /// Modules in the module collection class are stored as reference
  27 /// counted shared pointers to Module objects.
  28 //----------------------------------------------------------------------
  29 class ModuleList
  30 {
  31 public:
  32
  33     class Notifier
  34     {
  35     public:
  36         virtual void
  37         ModuleAdded (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
  38         virtual void
  39         ModuleRemoved (const ModuleList& module_list, const lldb::ModuleSP& module_sp) = 0;
  40         virtual void
  41         ModuleUpdated (const ModuleList& module_list, const lldb::ModuleSP& old_module_sp,
  42                        const lldb::ModuleSP& new_module_sp) = 0;
  43         virtual void
  44         WillClearList (const ModuleList& module_list) = 0;
  45
  46         virtual
  47         ~Notifier ()
  48         {}
  49     };
  50
  51     //------------------------------------------------------------------
  52     /// Default constructor.
  53     ///
  54     /// Creates an empty list of Module objects.
  55     //------------------------------------------------------------------
  56     ModuleList ();
  57
  58     //------------------------------------------------------------------
  59     /// Copy Constructor.
  60     ///
  61     /// Creates a new module list object with a copy of the modules from
  62     /// \a rhs.
  63     ///
  64     /// @param[in] rhs
  65     ///     Another module list object.
  66     //------------------------------------------------------------------
  67     ModuleList (const ModuleList& rhs);
  68
  69     ModuleList (ModuleList::Notifier* notifier);
  70
  71     //------------------------------------------------------------------
  72     /// Destructor.
  73     //------------------------------------------------------------------
  74     ~ModuleList ();
  75
  76     //------------------------------------------------------------------
  77     /// Assignment operator.
  78     ///
  79     /// Copies the module list from \a rhs into this list.
  80     ///
  81     /// @param[in] rhs
  82     ///     Another module list object.
  83     ///
  84     /// @return
  85     ///     A const reference to this object.
  86     //------------------------------------------------------------------
  87     const ModuleList&
  88     operator= (const ModuleList& rhs);
  89
  90     //------------------------------------------------------------------
  91     /// Append a module to the module list.
  92     ///
  93     /// Appends the module to the collection.
  94     ///
  95     /// @param[in] module_sp
  96     ///     A shared pointer to a module to add to this collection.
  97     //------------------------------------------------------------------
  98     void
  99     Append (const lldb::ModuleSP &module_sp);
 100
 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.
 105     ///
 106     /// Replaces the module to the collection.
 107     ///
 108     /// @param[in] module_sp
 109     ///     A shared pointer to a module to replace in this collection.
 110     //------------------------------------------------------------------
 111     void
 112     ReplaceEquivalent (const lldb::ModuleSP &module_sp);
 113
 114     bool
 115     AppendIfNeeded (const lldb::ModuleSP &module_sp);
 116
 117     void
 118     Append (const ModuleList& module_list);
 119
 120     bool
 121     AppendIfNeeded (const ModuleList& module_list);
 122
 123     bool
 124     ReplaceModule (const lldb::ModuleSP &old_module_sp, const lldb::ModuleSP &new_module_sp);
 125
 126     //------------------------------------------------------------------
 127     /// Clear the object's state.
 128     ///
 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     //------------------------------------------------------------------
 133     void
 134     Clear ();
 135
 136     //------------------------------------------------------------------
 137     /// Clear the object's state.
 138     ///
 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     //------------------------------------------------------------------
 144     void
 145     Destroy();
 146     //------------------------------------------------------------------
 147     /// Dump the description of each module contained in this list.
 148     ///
 149     /// Dump the description of each module contained in this list to
 150     /// the supplied stream \a s.
 151     ///
 152     /// @param[in] s
 153     ///     The stream to which to dump the object description.
 154     ///
 155     /// @see Module::Dump(Stream *) const
 156     //------------------------------------------------------------------
 157     void
 158     Dump (Stream *s) const;
 159
 160     void
 161     LogUUIDAndPaths (Log *log, const char *prefix_cstr);
 162
 163     Mutex &
 164     GetMutex () const
 165     {
 166         return m_modules_mutex;
 167     }
 168
 169     size_t
 170     GetIndexForModule (const Module *module) const;
 171
 172     //------------------------------------------------------------------
 173     /// Get the module shared pointer for the module at index \a idx.
 174     ///
 175     /// @param[in] idx
 176     ///     An index into this module collection.
 177     ///
 178     /// @return
 179     ///     A shared pointer to a Module which can contain NULL if
 180     ///     \a idx is out of range.
 181     ///
 182     /// @see ModuleList::GetSize()
 183     //------------------------------------------------------------------
 184     lldb::ModuleSP
 185     GetModuleAtIndex (size_t idx) const;
 186
 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.
 191     ///
 192     /// @param[in] idx
 193     ///     An index into this module collection.
 194     ///
 195     /// @return
 196     ///     A shared pointer to a Module which can contain NULL if
 197     ///     \a idx is out of range.
 198     ///
 199     /// @see ModuleList::GetSize()
 200     //------------------------------------------------------------------
 201     lldb::ModuleSP
 202     GetModuleAtIndexUnlocked (size_t idx) const;
 203
 204     //------------------------------------------------------------------
 205     /// Get the module pointer for the module at index \a idx.
 206     ///
 207     /// @param[in] idx
 208     ///     An index into this module collection.
 209     ///
 210     /// @return
 211     ///     A pointer to a Module which can by NULL if \a idx is out
 212     ///     of range.
 213     ///
 214     /// @see ModuleList::GetSize()
 215     //------------------------------------------------------------------
 216     Module*
 217     GetModulePointerAtIndex (size_t idx) const;
 218
 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.
 223     ///
 224     /// @param[in] idx
 225     ///     An index into this module collection.
 226     ///
 227     /// @return
 228     ///     A pointer to a Module which can by NULL if \a idx is out
 229     ///     of range.
 230     ///
 231     /// @see ModuleList::GetSize()
 232     //------------------------------------------------------------------
 233     Module*
 234     GetModulePointerAtIndexUnlocked (size_t idx) const;
 235
 236     //------------------------------------------------------------------
 237     /// Find compile units by partial or full path.
 238     ///
 239     /// Finds all compile units that match \a path in all of the modules
 240     /// and returns the results in \a sc_list.
 241     ///
 242     /// @param[in] path
 243     ///     The name of the compile unit we are looking for.
 244     ///
 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.
 249     ///
 250     /// @param[out] sc_list
 251     ///     A symbol context list that gets filled in with all of the
 252     ///     matches.
 253     ///
 254     /// @return
 255     ///     The number of matches added to \a sc_list.
 256     //------------------------------------------------------------------
 257     size_t
 258     FindCompileUnits (const FileSpec &path,
 259                       bool append,
 260                       SymbolContextList &sc_list) const;
 261
 262     //------------------------------------------------------------------
 263     /// @see Module::FindFunctions ()
 264     //------------------------------------------------------------------
 265     size_t
 266     FindFunctions (const ConstString &name,
 267                    uint32_t name_type_mask,
 268                    bool include_symbols,
 269                    bool include_inlines,
 270                    bool append,
 271                    SymbolContextList &sc_list) const;
 272
 273     //------------------------------------------------------------------
 274     /// @see Module::FindFunctionSymbols ()
 275     //------------------------------------------------------------------
 276     size_t
 277     FindFunctionSymbols (const ConstString &name,
 278                          uint32_t name_type_mask,
 279                          SymbolContextList& sc_list);
 280
 281     //------------------------------------------------------------------
 282     /// @see Module::FindFunctions ()
 283     //------------------------------------------------------------------
 284     size_t
 285         FindFunctions(const RegularExpression &name,
 286         bool include_symbols,
 287         bool include_inlines,
 288         bool append,
 289         SymbolContextList& sc_list);
 290
 291     //------------------------------------------------------------------
 292     /// Find global and static variables by name.
 293     ///
 294     /// @param[in] name
 295     ///     The name of the global or static variable we are looking
 296     ///     for.
 297     ///
 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.
 302     ///
 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.
 306     ///
 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).
 310     ///
 311     /// @return
 312     ///     The number of matches added to \a variable_list.
 313     //------------------------------------------------------------------
 314     size_t
 315     FindGlobalVariables (const ConstString &name,
 316                          bool append,
 317                          size_t max_matches,
 318                          VariableList& variable_list) const;
 319
 320     //------------------------------------------------------------------
 321     /// Find global and static variables by regular expression.
 322     ///
 323     /// @param[in] regex
 324     ///     A regular expression to use when matching the name.
 325     ///
 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.
 330     ///
 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.
 334     ///
 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).
 338     ///
 339     /// @return
 340     ///     The number of matches added to \a variable_list.
 341     //------------------------------------------------------------------
 342     size_t
 343     FindGlobalVariables (const RegularExpression& regex,
 344                          bool append,
 345                          size_t max_matches,
 346                          VariableList& variable_list) const;
 347
 348     //------------------------------------------------------------------
 349     /// Finds the first module whose file specification matches \a
 350     /// file_spec.
 351     ///
 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.
 359     ///
 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.
 363     ///
 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.
 367     ///
 368     /// @param[in] object_name
 369     ///     An optional object name that must match as well. This value
 370     ///     can be NULL.
 371     ///
 372     /// @param[out] matching_module_list
 373     ///     A module list that gets filled in with any modules that
 374     ///     match the search criteria.
 375     ///
 376     /// @return
 377     ///     The number of matching modules found by the search.
 378     //------------------------------------------------------------------
 379     size_t
 380     FindModules (const ModuleSpec &module_spec,
 381                  ModuleList& matching_module_list) const;
 382
 383     lldb::ModuleSP
 384     FindModule (const Module *module_ptr) const;
 385
 386     //------------------------------------------------------------------
 387     // Find a module by UUID
 388     //
 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     //------------------------------------------------------------------
 393     lldb::ModuleSP
 394     FindModule (const UUID &uuid) const;
 395
 396     lldb::ModuleSP
 397     FindFirstModule (const ModuleSpec &module_spec) const;
 398
 399     size_t
 400     FindSymbolsWithNameAndType (const ConstString &name,
 401                                 lldb::SymbolType symbol_type,
 402                                 SymbolContextList &sc_list,
 403                                 bool append = false) const;
 404
 405     size_t
 406     FindSymbolsMatchingRegExAndType (const RegularExpression &regex,
 407                                      lldb::SymbolType symbol_type,
 408                                      SymbolContextList &sc_list,
 409                                      bool append = false) const;
 410
 411     //------------------------------------------------------------------
 412     /// Find types by name.
 413     ///
 414     /// @param[in] sc
 415     ///     A symbol context that scopes where to extract a type list
 416     ///     from.
 417     ///
 418     /// @param[in] name
 419     ///     The name of the type we are looking for.
 420     ///
 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.
 425     ///
 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.
 429     ///
 430     /// @param[in] encoding
 431     ///     Limit the search to specific types, or get all types if
 432     ///     set to Type::invalid.
 433     ///
 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).
 437     ///
 438     /// @param[out] type_list
 439     ///     A type list gets populated with any matches.
 440     ///
 441     /// @return
 442     ///     The number of matches added to \a type_list.
 443     //------------------------------------------------------------------
 444     size_t
 445     FindTypes (const SymbolContext& sc,
 446                const ConstString &name,
 447                bool name_is_fully_qualified,
 448                size_t max_matches,
 449                TypeList& types) const;
 450
 451     bool
 452     FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
 453
 454
 455     //------------------------------------------------------------------
 456     /// Find addresses by file/line
 457     ///
 458     /// @param[in] target_sp
 459     ///     The target the addresses are desired for.
 460     ///
 461     /// @param[in] file
 462     ///     Source file to locate.
 463     ///
 464     /// @param[in] line
 465     ///     Source line to locate.
 466     ///
 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.
 470     ///
 471     /// @param[out] output_local
 472     ///     All matching addresses within 'function'
 473     ///
 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,
 478                                Function *function,
 479                                std::vector<Address> &output_local, std::vector<Address> &output_extern);
 480
 481
 482     bool
 483     Remove (const lldb::ModuleSP &module_sp);
 484
 485     size_t
 486     Remove (ModuleList &module_list);
 487
 488     bool
 489     RemoveIfOrphaned (const Module *module_ptr);
 490
 491     size_t
 492     RemoveOrphans (bool mandatory);
 493
 494     bool
 495     ResolveFileAddress (lldb::addr_t vm_addr,
 496                         Address& so_addr) const;
 497
 498     //------------------------------------------------------------------
 499     /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
 500     //------------------------------------------------------------------
 501     uint32_t
 502     ResolveSymbolContextForAddress (const Address& so_addr,
 503                                     uint32_t resolve_scope,
 504                                     SymbolContext& sc) const;
 505
 506     //------------------------------------------------------------------
 507     /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
 508     //------------------------------------------------------------------
 509     uint32_t
 510     ResolveSymbolContextForFilePath (const char *file_path,
 511                                      uint32_t line,
 512                                      bool check_inlines,
 513                                      uint32_t resolve_scope,
 514                                      SymbolContextList& sc_list) const;
 515
 516     //------------------------------------------------------------------
 517     /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
 518     //------------------------------------------------------------------
 519     uint32_t
 520     ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
 521                                      uint32_t line,
 522                                      bool check_inlines,
 523                                      uint32_t resolve_scope,
 524                                      SymbolContextList& sc_list) const;
 525
 526     //------------------------------------------------------------------
 527     /// Gets the size of the module list.
 528     ///
 529     /// @return
 530     ///     The number of modules in the module list.
 531     //------------------------------------------------------------------
 532     size_t
 533     GetSize () const;
 534
 535     bool
 536     LoadScriptingResourcesInTarget (Target *target,
 537                                     std::list<Error>& errors,
 538                                     Stream* feedback_stream = NULL,
 539                                     bool continue_on_error = true);
 540
 541     static bool
 542     ModuleIsInCache (const Module *module_ptr);
 543
 544     static Error
 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);
 551
 552     static bool
 553     RemoveSharedModule (lldb::ModuleSP &module_sp);
 554
 555     static size_t
 556     FindSharedModules (const ModuleSpec &module_spec,
 557                        ModuleList &matching_module_list);
 558
 559     static size_t
 560     RemoveOrphanSharedModules (bool mandatory);
 561
 562     static bool
 563     RemoveSharedModuleIfOrphaned (const Module *module_ptr);
 564
 565 protected:
 566     //------------------------------------------------------------------
 567     // Class typedefs.
 568     //------------------------------------------------------------------
 569     typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
 570
 571     void
 572     AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 573
 574     bool
 575     RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 576
 577     collection::iterator
 578     RemoveImpl (collection::iterator pos, bool use_notifier = true);
 579
 580     void
 581     ClearImpl (bool use_notifier = true);
 582
 583     //------------------------------------------------------------------
 584     // Member variables.
 585     //------------------------------------------------------------------
 586     collection m_modules; ///< The collection of modules.
 587     mutable Mutex m_modules_mutex;
 588
 589     Notifier* m_notifier;
 590
 591 public:
 592     typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterable;
 593     ModuleIterable
 594     Modules()
 595     {
 596         return ModuleIterable(m_modules, GetMutex());
 597     }
 598
 599     typedef AdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterableNoLocking;
 600     ModuleIterableNoLocking
 601     ModulesNoLocking ()
 602     {
 603         return ModuleIterableNoLocking(m_modules);
 604     }
 605
 606 };
 607
 608 } // namespace lldb_private
 609
 610 #endif  // liblldb_ModuleList_h_