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 () {}
 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 //----------------------------------------------------------------------
 290 /// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
 291 /// @brief This is a SearchFilter that restricts the search to a given module.
 292 //----------------------------------------------------------------------
 293
 294 class SearchFilterByModule :
 295     public SearchFilter
 296 {
 297 public:
 298
 299     //------------------------------------------------------------------
 300     /// The basic constructor takes a Target, which gives the space to search,
 301     /// and the module to restrict the search to.
 302     ///
 303     /// @param[in] target
 304     ///    The Target that provides the module list to search.
 305     ///
 306     /// @param[in] module
 307     ///    The Module that limits the search.
 308     //------------------------------------------------------------------
 309     SearchFilterByModule (const lldb::TargetSP &targetSP,
 310                           const FileSpec &module);
 311
 312     SearchFilterByModule (const SearchFilterByModule& rhs);
 313
 314     virtual
 315     ~SearchFilterByModule ();
 316
 317     const SearchFilterByModule&
 318     operator=(const SearchFilterByModule& rhs);
 319
 320     bool
 321     ModulePasses (const lldb::ModuleSP &module_sp) override;
 322
 323     bool
 324     ModulePasses (const FileSpec &spec) override;
 325
 326     bool
 327     AddressPasses (Address &address) override;
 328
 329     bool
 330     CompUnitPasses (FileSpec &fileSpec) override;
 331
 332     bool
 333     CompUnitPasses (CompileUnit &compUnit) override;
 334
 335     void
 336     GetDescription(Stream *s) override;
 337
 338     uint32_t
 339     GetFilterRequiredItems () override;
 340
 341     void
 342     Dump (Stream *s) const override;
 343
 344     void
 345     Search (Searcher &searcher) override;
 346
 347 protected:
 348     lldb::SearchFilterSP
 349     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 350
 351 private:
 352     FileSpec m_module_spec;
 353 };
 354
 355 class SearchFilterByModuleList :
 356     public SearchFilter
 357 {
 358 public:
 359
 360     //------------------------------------------------------------------
 361     /// The basic constructor takes a Target, which gives the space to search,
 362     /// and the module list to restrict the search to.
 363     ///
 364     /// @param[in] target
 365     ///    The Target that provides the module list to search.
 366     ///
 367     /// @param[in] module
 368     ///    The Module that limits the search.
 369     //------------------------------------------------------------------
 370     SearchFilterByModuleList (const lldb::TargetSP &targetSP,
 371                               const FileSpecList &module_list);
 372
 373     SearchFilterByModuleList (const SearchFilterByModuleList& rhs);
 374
 375     virtual
 376     ~SearchFilterByModuleList ();
 377
 378     const SearchFilterByModuleList&
 379     operator=(const SearchFilterByModuleList& rhs);
 380
 381     bool
 382     ModulePasses (const lldb::ModuleSP &module_sp) override;
 383
 384     bool
 385     ModulePasses (const FileSpec &spec) override;
 386
 387     bool
 388     AddressPasses (Address &address) override;
 389
 390     bool
 391     CompUnitPasses (FileSpec &fileSpec) override;
 392
 393     bool
 394     CompUnitPasses (CompileUnit &compUnit) override;
 395
 396     void
 397     GetDescription(Stream *s) override;
 398
 399     uint32_t
 400     GetFilterRequiredItems () override;
 401
 402     void
 403     Dump (Stream *s) const override;
 404
 405     void
 406     Search (Searcher &searcher) override;
 407
 408 protected:
 409     lldb::SearchFilterSP
 410     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 411
 412 private:
 413     FileSpecList m_module_spec_list;
 414 };
 415
 416 class SearchFilterByModuleListAndCU :
 417     public SearchFilterByModuleList
 418 {
 419 public:
 420
 421     //------------------------------------------------------------------
 422     /// The basic constructor takes a Target, which gives the space to search,
 423     /// and the module list to restrict the search to.
 424     ///
 425     /// @param[in] target
 426     ///    The Target that provides the module list to search.
 427     ///
 428     /// @param[in] module
 429     ///    The Module that limits the search.
 430     //------------------------------------------------------------------
 431     SearchFilterByModuleListAndCU (const lldb::TargetSP &targetSP,
 432                                    const FileSpecList &module_list,
 433                                    const FileSpecList &cu_list);
 434
 435     SearchFilterByModuleListAndCU (const SearchFilterByModuleListAndCU& rhs);
 436
 437     virtual
 438     ~SearchFilterByModuleListAndCU ();
 439
 440     const SearchFilterByModuleListAndCU&
 441     operator=(const SearchFilterByModuleListAndCU& rhs);
 442
 443     bool
 444     AddressPasses (Address &address) override;
 445
 446     bool
 447     CompUnitPasses (FileSpec &fileSpec) override;
 448
 449     bool
 450     CompUnitPasses (CompileUnit &compUnit) override;
 451
 452     void
 453     GetDescription(Stream *s) override;
 454
 455     uint32_t
 456     GetFilterRequiredItems () override;
 457
 458     void
 459     Dump (Stream *s) const override;
 460
 461     void
 462     Search (Searcher &searcher) override;
 463
 464 protected:
 465     lldb::SearchFilterSP
 466     DoCopyForBreakpoint (Breakpoint &breakpoint) override;
 467
 468 private:
 469     FileSpecList m_module_spec_list;
 470     FileSpecList m_cu_spec_list;
 471 };
 472
 473 } // namespace lldb_private
 474
 475 #endif  // liblldb_SearchFilter_h_