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

   1 //===-- SearchFilter.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_SearchFilter_h_
  11 #define liblldb_SearchFilter_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 // Other libraries and framework includes
  16 // Project includes
  17 #include "lldb/lldb-private.h"
  18 #include "lldb/Core/FileSpecList.h"
  19
  20 namespace lldb_private {
  21
  22 //----------------------------------------------------------------------
  23 /// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h"
  24 /// @brief Class that is driven by the SearchFilter to search the
  25 /// SymbolContext space of the target program.
  26 //----------------------------------------------------------------------
  27
  28 //----------------------------------------------------------------------
  29 /// General Outline:
  30 /// Provides the callback and search depth for the SearchFilter search.
  31 //----------------------------------------------------------------------
  32
  33 class Searcher
  34 {
  35 public:
  36     typedef enum {
  37         eCallbackReturnStop = 0,  // Stop the iteration
  38         eCallbackReturnContinue,  // Continue the iteration
  39         eCallbackReturnPop        // Pop one level up and continue iterating
  40     } CallbackReturn;
  41
  42     typedef enum {
  43         eDepthTarget,
  44         eDepthModule,
  45         eDepthCompUnit,
  46         eDepthFunction,
  47         eDepthBlock,
  48         eDepthAddress
  49     } Depth;
  50
  51     Searcher ();
  52
  53     virtual ~Searcher ();
  54
  55     virtual CallbackReturn
  56     SearchCallback (SearchFilter &filter,
  57                     SymbolContext &context,
  58                     Address *addr,
  59                     bool complete) = 0;
  60
  61     virtual Depth
  62     GetDepth () = 0;
  63
  64     //------------------------------------------------------------------
  65     /// Prints a canonical description for the searcher to the stream \a s.
  66     ///
  67     /// @param[in] s
  68     ///   Stream to which the output is copied.
  69     //------------------------------------------------------------------
  70     virtual void
  71     GetDescription(Stream *s);
  72 };
  73
  74 //----------------------------------------------------------------------
  75 /// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h"
  76 /// @brief Class descends through the SymbolContext space of the target,
  77 /// applying a filter at each stage till it reaches the depth specified by
  78 /// the GetDepth method of the searcher, and calls its callback at that point.
  79 //----------------------------------------------------------------------
  80
  81 //----------------------------------------------------------------------
  82 /// General Outline:
  83 /// Provides the callback and search depth for the SearchFilter search.
  84 ///
  85 /// The search is done by cooperation between the search filter and the searcher.
  86 /// The search filter does the heavy work of recursing through the SymbolContext
  87 /// space of the target program's symbol space.  The Searcher specifies the depth
  88 /// at which it wants its callback to be invoked.  Note that since the resolution
  89 /// of the Searcher may be greater than that of the SearchFilter, before the
  90 /// Searcher qualifies an address it should pass it to "AddressPasses."
  91 /// The default implementation is "Everything Passes."
  92 //----------------------------------------------------------------------
  93
  94 class SearchFilter
  95 {
  96 public:
  97
  98     //------------------------------------------------------------------
  99     /// The basic constructor takes a Target, which gives the space to search.
 100     ///
 101     /// @param[in] target
 102     ///    The Target that provides the module list to search.
 103     //------------------------------------------------------------------
 104     SearchFilter (const lldb::TargetSP &target_sp);
 105
 106     SearchFilter (const SearchFilter& rhs);
 107
 108     virtual
 109     ~SearchFilter ();
 110
 111     const SearchFilter&
 112     operator=(const SearchFilter& rhs);
 113
 114     //------------------------------------------------------------------
 115     /// Call this method with a file spec to see if that spec passes the filter.
 116     ///
 117     /// @param[in] spec
 118     ///    The file spec to check against the filter.
 119     /// @return
 120     ///    \b true if \a spec passes, and \b false otherwise.
 121     //------------------------------------------------------------------
 122     virtual bool
 123     ModulePasses (const FileSpec &spec);
 124
 125     //------------------------------------------------------------------
 126     /// Call this method with a Module to see if that module passes the filter.
 127     ///
 128     /// @param[in] module
 129     ///    The Module to check against the filter.
 130     ///
 131     /// @return
 132     ///    \b true if \a module passes, and \b false otherwise.
 133     //------------------------------------------------------------------
 134     virtual bool
 135     ModulePasses (const lldb::ModuleSP &module_sp);
 136
 137     //------------------------------------------------------------------
 138     /// Call this method with a Address to see if \a address passes the filter.
 139     ///
 140     /// @param[in] addr
 141     ///    The address to check against the filter.
 142     ///
 143     /// @return
 144     ///    \b true if \a address passes, and \b false otherwise.
 145     //------------------------------------------------------------------
 146     virtual bool
 147     AddressPasses (Address &addr);
 148
 149     //------------------------------------------------------------------
 150     /// Call this method with a FileSpec to see if \a file spec passes the filter
 151     /// as the name of a compilation unit.
 152     ///
 153     /// @param[in] fileSpec
 154     ///    The file spec to check against the filter.
 155     ///
 156     /// @return
 157     ///    \b true if \a file spec passes, and \b false otherwise.
 158     //------------------------------------------------------------------
 159     virtual bool
 160     CompUnitPasses (FileSpec &fileSpec);
 161
 162     //------------------------------------------------------------------
 163     /// Call this method with a CompileUnit to see if \a comp unit passes the filter.
 164     ///
 165     /// @param[in] compUnit
 166     ///    The CompileUnit to check against the filter.
 167     ///
 168     /// @return
 169     ///    \b true if \a Comp Unit passes, and \b false otherwise.
 170     //------------------------------------------------------------------
 171     virtual bool
 172     CompUnitPasses (CompileUnit &compUnit);
 173
 174     //------------------------------------------------------------------
 175     /// Call this method to do the search using the Searcher.
 176     ///
 177     /// @param[in] searcher
 178     ///    The searcher to drive with this search.
 179     ///
 180     //------------------------------------------------------------------
 181     virtual void
 182     Search (Searcher &searcher);
 183
 184     //------------------------------------------------------------------
 185     /// Call this method to do the search using the Searcher in the module list
 186     /// \a modules.
 187     ///
 188     /// @param[in] searcher
 189     ///    The searcher to drive with this search.
 190     ///
 191     /// @param[in] modules
 192     ///    The module list within which to restrict the search.
 193     ///
 194     //------------------------------------------------------------------
 195     virtual void
 196     SearchInModuleList (Searcher &searcher, ModuleList &modules);
 197
 198     //------------------------------------------------------------------
 199     /// This determines which items are REQUIRED for the filter to pass.
 200     /// For instance, if you are filtering by Compilation Unit, obviously
 201     /// symbols that have no compilation unit can't pass  So return eSymbolContextCU
 202     /// and search callbacks can then short cut the search to avoid looking at
 203     /// things that obviously won't pass.
 204     ///
 205     /// @return
 206     ///    The required elements for the search, which is an or'ed together
 207     ///    set of lldb:SearchContextItem enum's.
 208     ///
 209     //------------------------------------------------------------------
 210     virtual uint32_t
 211     GetFilterRequiredItems ();
 212
 213     //------------------------------------------------------------------
 214     /// Prints a canonical description for the search filter to the stream \a s.
 215     ///
 216     /// @param[in] s
 217     ///   Stream to which the output is copied.
 218     //------------------------------------------------------------------
 219     virtual void
 220     GetDescription(Stream *s);
 221
 222     //------------------------------------------------------------------
 223     /// Standard "Dump" method.  At present it does nothing.
 224     //------------------------------------------------------------------
 225     virtual void
 226     Dump (Stream *s) const;
 227
 228     lldb::SearchFilterSP
 229     CopyForBreakpoint (Breakpoint &breakpoint);
 230
 231 protected:
 232     // These are utility functions to assist with the search iteration.  They are used by the
 233     // default Search method.
 234
 235     Searcher::CallbackReturn
 236     DoModuleIteration (const SymbolContext &context,
 237                        Searcher &searcher);
 238
 239     Searcher::CallbackReturn
 240     DoModuleIteration (const lldb::ModuleSP& module_sp,
 241                        Searcher &searcher);
 242
 243     Searcher::CallbackReturn
 244     DoCUIteration (const lldb::ModuleSP& module_sp,
 245                    const SymbolContext &context,
 246                    Searcher &searcher);
 247
 248     Searcher::CallbackReturn
 249     DoFunctionIteration (Function *function,
 250                          const SymbolContext &context,
 251                          Searcher &searcher);
 252
 253     virtual lldb::SearchFilterSP
 254     DoCopyForBreakpoint (Breakpoint &breakpoint) = 0;
 255
 256     void
 257     SetTarget(lldb::TargetSP &target_sp)
 258     {
 259         m_target_sp = target_sp;
 260     }
 261
 262     lldb::TargetSP m_target_sp;   // Every filter has to be associated with a target for
 263                                   // now since you need a starting place for the search.
 264 };
 265
 266 //----------------------------------------------------------------------
 267 /// @class SearchFilterForUnconstrainedSearches SearchFilter.h "lldb/Core/SearchFilter.h"
 268 /// @brief This is a SearchFilter that searches through all modules.  It also consults the Target::ModuleIsExcludedForUnconstrainedSearches.
 269 //----------------------------------------------------------------------
 270 class SearchFilterForUnconstrainedSearches :
 271     public SearchFilter
 272 {
 273 public:
 274     SearchFilterForUnconstrainedSearches (const lldb::TargetSP &target_sp) : SearchFilter(target_sp) {}
 275     ~SearchFilterForUnconstrainedSearches() override = default;
 276
 277     bool
 278     ModulePasses (const FileSpec &module_spec) override;
 279
 280     bool
 281     ModulePasses (const lldb::ModuleSP &module_sp) override;
 282
 283 protected:
 284     lldb::SearchFilterSP
 285     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 286 };
 287
 288 //----------------------------------------------------------------------
 289 /// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
 290 /// @brief This is a SearchFilter that restricts the search to a given module.
 291 //----------------------------------------------------------------------
 292
 293 class SearchFilterByModule :
 294     public SearchFilter
 295 {
 296 public:
 297
 298     //------------------------------------------------------------------
 299     /// The basic constructor takes a Target, which gives the space to search,
 300     /// and the module to restrict the search to.
 301     ///
 302     /// @param[in] target
 303     ///    The Target that provides the module list to search.
 304     ///
 305     /// @param[in] module
 306     ///    The Module that limits the search.
 307     //------------------------------------------------------------------
 308     SearchFilterByModule (const lldb::TargetSP &targetSP,
 309                           const FileSpec &module);
 310
 311     SearchFilterByModule (const SearchFilterByModule& rhs);
 312
 313     ~SearchFilterByModule() override;
 314
 315     const SearchFilterByModule&
 316     operator=(const SearchFilterByModule& rhs);
 317
 318     bool
 319     ModulePasses (const lldb::ModuleSP &module_sp) override;
 320
 321     bool
 322     ModulePasses (const FileSpec &spec) override;
 323
 324     bool
 325     AddressPasses (Address &address) override;
 326
 327     bool
 328     CompUnitPasses (FileSpec &fileSpec) override;
 329
 330     bool
 331     CompUnitPasses (CompileUnit &compUnit) override;
 332
 333     void
 334     GetDescription(Stream *s) override;
 335
 336     uint32_t
 337     GetFilterRequiredItems () override;
 338
 339     void
 340     Dump (Stream *s) const override;
 341
 342     void
 343     Search (Searcher &searcher) override;
 344
 345 protected:
 346     lldb::SearchFilterSP
 347     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 348
 349 private:
 350     FileSpec m_module_spec;
 351 };
 352
 353 class SearchFilterByModuleList :
 354     public SearchFilter
 355 {
 356 public:
 357
 358     //------------------------------------------------------------------
 359     /// The basic constructor takes a Target, which gives the space to search,
 360     /// and the module list to restrict the search to.
 361     ///
 362     /// @param[in] target
 363     ///    The Target that provides the module list to search.
 364     ///
 365     /// @param[in] module
 366     ///    The Module that limits the search.
 367     //------------------------------------------------------------------
 368     SearchFilterByModuleList (const lldb::TargetSP &targetSP,
 369                               const FileSpecList &module_list);
 370
 371     SearchFilterByModuleList (const SearchFilterByModuleList& rhs);
 372
 373     ~SearchFilterByModuleList() override;
 374
 375     const SearchFilterByModuleList&
 376     operator=(const SearchFilterByModuleList& rhs);
 377
 378     bool
 379     ModulePasses (const lldb::ModuleSP &module_sp) override;
 380
 381     bool
 382     ModulePasses (const FileSpec &spec) override;
 383
 384     bool
 385     AddressPasses (Address &address) override;
 386
 387     bool
 388     CompUnitPasses (FileSpec &fileSpec) override;
 389
 390     bool
 391     CompUnitPasses (CompileUnit &compUnit) override;
 392
 393     void
 394     GetDescription(Stream *s) override;
 395
 396     uint32_t
 397     GetFilterRequiredItems () override;
 398
 399     void
 400     Dump (Stream *s) const override;
 401
 402     void
 403     Search (Searcher &searcher) override;
 404
 405 protected:
 406     lldb::SearchFilterSP
 407     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 408
 409 protected:
 410     FileSpecList m_module_spec_list;
 411 };
 412
 413 class SearchFilterByModuleListAndCU :
 414     public SearchFilterByModuleList
 415 {
 416 public:
 417
 418     //------------------------------------------------------------------
 419     /// The basic constructor takes a Target, which gives the space to search,
 420     /// and the module list to restrict the search to.
 421     ///
 422     /// @param[in] target
 423     ///    The Target that provides the module list to search.
 424     ///
 425     /// @param[in] module
 426     ///    The Module that limits the search.
 427     //------------------------------------------------------------------
 428     SearchFilterByModuleListAndCU (const lldb::TargetSP &targetSP,
 429                                    const FileSpecList &module_list,
 430                                    const FileSpecList &cu_list);
 431
 432     SearchFilterByModuleListAndCU (const SearchFilterByModuleListAndCU& rhs);
 433
 434     ~SearchFilterByModuleListAndCU() override;
 435
 436     const SearchFilterByModuleListAndCU&
 437     operator=(const SearchFilterByModuleListAndCU& rhs);
 438
 439     bool
 440     AddressPasses (Address &address) override;
 441
 442     bool
 443     CompUnitPasses (FileSpec &fileSpec) override;
 444
 445     bool
 446     CompUnitPasses (CompileUnit &compUnit) override;
 447
 448     void
 449     GetDescription(Stream *s) override;
 450
 451     uint32_t
 452     GetFilterRequiredItems () override;
 453
 454     void
 455     Dump (Stream *s) const override;
 456
 457     void
 458     Search (Searcher &searcher) override;
 459
 460 protected:
 461     lldb::SearchFilterSP
 462     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 463
 464 private:
 465     FileSpecList m_cu_spec_list;
 466 };
 467
 468 } // namespace lldb_private
 469
 470 #endif // liblldb_SearchFilter_h_