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     /// Find global and static variables by name.
 283     ///
 284     /// @param[in] name
 285     ///     The name of the global or static variable we are looking
 286     ///     for.
 287     ///
 288     /// @param[in] append
 289     ///     If \b true, any matches will be appended to \a
 290     ///     variable_list, else matches replace the contents of
 291     ///     \a variable_list.
 292     ///
 293     /// @param[in] max_matches
 294     ///     Allow the number of matches to be limited to \a
 295     ///     max_matches. Specify UINT32_MAX to get all possible matches.
 296     ///
 297     /// @param[in] variable_list
 298     ///     A list of variables that gets the matches appended to (if
 299     ///     \a append it \b true), or replace (if \a append is \b false).
 300     ///
 301     /// @return
 302     ///     The number of matches added to \a variable_list.
 303     //------------------------------------------------------------------
 304     size_t
 305     FindGlobalVariables (const ConstString &name,
 306                          bool append,
 307                          size_t max_matches,
 308                          VariableList& variable_list) const;
 309
 310     //------------------------------------------------------------------
 311     /// Find global and static variables by regular expression.
 312     ///
 313     /// @param[in] regex
 314     ///     A regular expression to use when matching the name.
 315     ///
 316     /// @param[in] append
 317     ///     If \b true, any matches will be appended to \a
 318     ///     variable_list, else matches replace the contents of
 319     ///     \a variable_list.
 320     ///
 321     /// @param[in] max_matches
 322     ///     Allow the number of matches to be limited to \a
 323     ///     max_matches. Specify UINT32_MAX to get all possible matches.
 324     ///
 325     /// @param[in] variable_list
 326     ///     A list of variables that gets the matches appended to (if
 327     ///     \a append it \b true), or replace (if \a append is \b false).
 328     ///
 329     /// @return
 330     ///     The number of matches added to \a variable_list.
 331     //------------------------------------------------------------------
 332     size_t
 333     FindGlobalVariables (const RegularExpression& regex,
 334                          bool append,
 335                          size_t max_matches,
 336                          VariableList& variable_list) const;
 337
 338     //------------------------------------------------------------------
 339     /// Finds the first module whose file specification matches \a
 340     /// file_spec.
 341     ///
 342     /// @param[in] file_spec_ptr
 343     ///     A file specification object to match against the Module's
 344     ///     file specifications. If \a file_spec does not have
 345     ///     directory information, matches will occur by matching only
 346     ///     the basename of any modules in this list. If this value is
 347     ///     NULL, then file specifications won't be compared when
 348     ///     searching for matching modules.
 349     ///
 350     /// @param[in] arch_ptr
 351     ///     The architecture to search for if non-NULL. If this value
 352     ///     is NULL no architecture matching will be performed.
 353     ///
 354     /// @param[in] uuid_ptr
 355     ///     The uuid to search for if non-NULL. If this value is NULL
 356     ///     no uuid matching will be performed.
 357     ///
 358     /// @param[in] object_name
 359     ///     An optional object name that must match as well. This value
 360     ///     can be NULL.
 361     ///
 362     /// @param[out] matching_module_list
 363     ///     A module list that gets filled in with any modules that
 364     ///     match the search criteria.
 365     ///
 366     /// @return
 367     ///     The number of matching modules found by the search.
 368     //------------------------------------------------------------------
 369     size_t
 370     FindModules (const ModuleSpec &module_spec,
 371                  ModuleList& matching_module_list) const;
 372
 373     lldb::ModuleSP
 374     FindModule (const Module *module_ptr) const;
 375
 376     //------------------------------------------------------------------
 377     // Find a module by UUID
 378     //
 379     // The UUID value for a module is extracted from the ObjectFile and
 380     // is the MD5 checksum, or a smarter object file equivalent, so
 381     // finding modules by UUID values is very efficient and accurate.
 382     //------------------------------------------------------------------
 383     lldb::ModuleSP
 384     FindModule (const UUID &uuid) const;
 385
 386     lldb::ModuleSP
 387     FindFirstModule (const ModuleSpec &module_spec) const;
 388
 389     size_t
 390     FindSymbolsWithNameAndType (const ConstString &name,
 391                                 lldb::SymbolType symbol_type,
 392                                 SymbolContextList &sc_list,
 393                                 bool append = false) const;
 394
 395     size_t
 396     FindSymbolsMatchingRegExAndType (const RegularExpression &regex,
 397                                      lldb::SymbolType symbol_type,
 398                                      SymbolContextList &sc_list,
 399                                      bool append = false) const;
 400
 401     //------------------------------------------------------------------
 402     /// Find types by name.
 403     ///
 404     /// @param[in] sc
 405     ///     A symbol context that scopes where to extract a type list
 406     ///     from.
 407     ///
 408     /// @param[in] name
 409     ///     The name of the type we are looking for.
 410     ///
 411     /// @param[in] append
 412     ///     If \b true, any matches will be appended to \a
 413     ///     variable_list, else matches replace the contents of
 414     ///     \a variable_list.
 415     ///
 416     /// @param[in] max_matches
 417     ///     Allow the number of matches to be limited to \a
 418     ///     max_matches. Specify UINT32_MAX to get all possible matches.
 419     ///
 420     /// @param[in] encoding
 421     ///     Limit the search to specific types, or get all types if
 422     ///     set to Type::invalid.
 423     ///
 424     /// @param[in] udt_name
 425     ///     If the encoding is a user defined type, specify the name
 426     ///     of the user defined type ("struct", "union", "class", etc).
 427     ///
 428     /// @param[out] type_list
 429     ///     A type list gets populated with any matches.
 430     ///
 431     /// @return
 432     ///     The number of matches added to \a type_list.
 433     //------------------------------------------------------------------
 434     size_t
 435     FindTypes (const SymbolContext& sc,
 436                const ConstString &name,
 437                bool name_is_fully_qualified,
 438                size_t max_matches,
 439                TypeList& types) const;
 440
 441     bool
 442     FindSourceFile (const FileSpec &orig_spec, FileSpec &new_spec) const;
 443
 444
 445     //------------------------------------------------------------------
 446     /// Find addresses by file/line
 447     ///
 448     /// @param[in] target_sp
 449     ///     The target the addresses are desired for.
 450     ///
 451     /// @param[in] file
 452     ///     Source file to locate.
 453     ///
 454     /// @param[in] line
 455     ///     Source line to locate.
 456     ///
 457     /// @param[in] function
 458     ///     Optional filter function. Addresses within this function will be
 459     ///     added to the 'local' list. All others will be added to the 'extern' list.
 460     ///
 461     /// @param[out] output_local
 462     ///     All matching addresses within 'function'
 463     ///
 464     /// @param[out] output_extern
 465     ///     All matching addresses not within 'function'
 466     void FindAddressesForLine (const lldb::TargetSP target_sp,
 467                                const FileSpec &file, uint32_t line,
 468                                Function *function,
 469                                std::vector<Address> &output_local, std::vector<Address> &output_extern);
 470
 471
 472     bool
 473     Remove (const lldb::ModuleSP &module_sp);
 474
 475     size_t
 476     Remove (ModuleList &module_list);
 477
 478     bool
 479     RemoveIfOrphaned (const Module *module_ptr);
 480
 481     size_t
 482     RemoveOrphans (bool mandatory);
 483
 484     bool
 485     ResolveFileAddress (lldb::addr_t vm_addr,
 486                         Address& so_addr) const;
 487
 488     //------------------------------------------------------------------
 489     /// @copydoc Module::ResolveSymbolContextForAddress (const Address &,uint32_t,SymbolContext&)
 490     //------------------------------------------------------------------
 491     uint32_t
 492     ResolveSymbolContextForAddress (const Address& so_addr,
 493                                     uint32_t resolve_scope,
 494                                     SymbolContext& sc) const;
 495
 496     //------------------------------------------------------------------
 497     /// @copydoc Module::ResolveSymbolContextForFilePath (const char *,uint32_t,bool,uint32_t,SymbolContextList&)
 498     //------------------------------------------------------------------
 499     uint32_t
 500     ResolveSymbolContextForFilePath (const char *file_path,
 501                                      uint32_t line,
 502                                      bool check_inlines,
 503                                      uint32_t resolve_scope,
 504                                      SymbolContextList& sc_list) const;
 505
 506     //------------------------------------------------------------------
 507     /// @copydoc Module::ResolveSymbolContextsForFileSpec (const FileSpec &,uint32_t,bool,uint32_t,SymbolContextList&)
 508     //------------------------------------------------------------------
 509     uint32_t
 510     ResolveSymbolContextsForFileSpec (const FileSpec &file_spec,
 511                                      uint32_t line,
 512                                      bool check_inlines,
 513                                      uint32_t resolve_scope,
 514                                      SymbolContextList& sc_list) const;
 515
 516     //------------------------------------------------------------------
 517     /// Gets the size of the module list.
 518     ///
 519     /// @return
 520     ///     The number of modules in the module list.
 521     //------------------------------------------------------------------
 522     size_t
 523     GetSize () const;
 524
 525     bool
 526     LoadScriptingResourcesInTarget (Target *target,
 527                                     std::list<Error>& errors,
 528                                     Stream* feedback_stream = NULL,
 529                                     bool continue_on_error = true);
 530
 531     static bool
 532     ModuleIsInCache (const Module *module_ptr);
 533
 534     static Error
 535     GetSharedModule (const ModuleSpec &module_spec,
 536                      lldb::ModuleSP &module_sp,
 537                      const FileSpecList *module_search_paths_ptr,
 538                      lldb::ModuleSP *old_module_sp_ptr,
 539                      bool *did_create_ptr,
 540                      bool always_create = false);
 541
 542     static bool
 543     RemoveSharedModule (lldb::ModuleSP &module_sp);
 544
 545     static size_t
 546     FindSharedModules (const ModuleSpec &module_spec,
 547                        ModuleList &matching_module_list);
 548
 549     static size_t
 550     RemoveOrphanSharedModules (bool mandatory);
 551
 552     static bool
 553     RemoveSharedModuleIfOrphaned (const Module *module_ptr);
 554
 555 protected:
 556     //------------------------------------------------------------------
 557     // Class typedefs.
 558     //------------------------------------------------------------------
 559     typedef std::vector<lldb::ModuleSP> collection; ///< The module collection type.
 560
 561     void
 562     AppendImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 563
 564     bool
 565     RemoveImpl (const lldb::ModuleSP &module_sp, bool use_notifier = true);
 566
 567     collection::iterator
 568     RemoveImpl (collection::iterator pos, bool use_notifier = true);
 569
 570     void
 571     ClearImpl (bool use_notifier = true);
 572
 573     //------------------------------------------------------------------
 574     // Member variables.
 575     //------------------------------------------------------------------
 576     collection m_modules; ///< The collection of modules.
 577     mutable Mutex m_modules_mutex;
 578
 579     Notifier* m_notifier;
 580
 581 public:
 582     typedef LockingAdaptedIterable<collection, lldb::ModuleSP, vector_adapter> ModuleIterable;
 583     ModuleIterable
 584     Modules()
 585     {
 586         return ModuleIterable(m_modules, GetMutex());
 587     }
 588
 589 };
 590
 591 } // namespace lldb_private
 592
 593 #endif  // liblldb_ModuleList_h_