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 protected:
 229
 230     // These are utility functions to assist with the search iteration.  They are used by the
 231     // default Search method.
 232
 233     Searcher::CallbackReturn
 234     DoModuleIteration (const SymbolContext &context,
 235                        Searcher &searcher);
 236
 237     Searcher::CallbackReturn
 238     DoModuleIteration (const lldb::ModuleSP& module_sp,
 239                        Searcher &searcher);
 240
 241     Searcher::CallbackReturn
 242     DoCUIteration (const lldb::ModuleSP& module_sp,
 243                    const SymbolContext &context,
 244                    Searcher &searcher);
 245
 246     Searcher::CallbackReturn
 247     DoFunctionIteration (Function *function,
 248                          const SymbolContext &context,
 249                          Searcher &searcher);
 250
 251     lldb::TargetSP m_target_sp;   // Every filter has to be associated with a target for
 252                                   // now since you need a starting place for the search.
 253 };
 254
 255 //----------------------------------------------------------------------
 256 /// @class SearchFilterForNonModuleSpecificSearches SearchFilter.h "lldb/Core/SearchFilter.h"
 257 /// @brief This is a SearchFilter that searches through all modules.  It also consults the Target::ModuleIsExcludedForNonModuleSpecificSearches.
 258 //----------------------------------------------------------------------
 259 class SearchFilterForNonModuleSpecificSearches :
 260     public SearchFilter
 261 {
 262 public:
 263     SearchFilterForNonModuleSpecificSearches (const lldb::TargetSP &targetSP) : SearchFilter(targetSP) {}
 264     ~SearchFilterForNonModuleSpecificSearches () {}
 265
 266     virtual bool
 267     ModulePasses (const FileSpec &module_spec);
 268
 269     virtual bool
 270     ModulePasses (const lldb::ModuleSP &module_sp);
 271 };
 272
 273 //----------------------------------------------------------------------
 274 /// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h"
 275 /// @brief This is a SearchFilter that restricts the search to a given module.
 276 //----------------------------------------------------------------------
 277
 278 class SearchFilterByModule :
 279     public SearchFilter
 280 {
 281 public:
 282
 283     //------------------------------------------------------------------
 284     /// The basic constructor takes a Target, which gives the space to search,
 285     /// and the module to restrict the search to.
 286     ///
 287     /// @param[in] target
 288     ///    The Target that provides the module list to search.
 289     ///
 290     /// @param[in] module
 291     ///    The Module that limits the search.
 292     //------------------------------------------------------------------
 293     SearchFilterByModule (const lldb::TargetSP &targetSP,
 294                           const FileSpec &module);
 295
 296     SearchFilterByModule (const SearchFilterByModule& rhs);
 297
 298     virtual
 299     ~SearchFilterByModule ();
 300
 301     const SearchFilterByModule&
 302     operator=(const SearchFilterByModule& rhs);
 303
 304     virtual bool
 305     ModulePasses (const lldb::ModuleSP &module_sp);
 306
 307     virtual bool
 308     ModulePasses (const FileSpec &spec);
 309
 310     virtual bool
 311     AddressPasses (Address &address);
 312
 313     virtual bool
 314     CompUnitPasses (FileSpec &fileSpec);
 315
 316     virtual bool
 317     CompUnitPasses (CompileUnit &compUnit);
 318
 319     virtual void
 320     GetDescription(Stream *s);
 321
 322     virtual uint32_t
 323     GetFilterRequiredItems ();
 324
 325     virtual void
 326     Dump (Stream *s) const;
 327
 328     virtual void
 329     Search (Searcher &searcher);
 330
 331 private:
 332     FileSpec m_module_spec;
 333 };
 334
 335 class SearchFilterByModuleList :
 336     public SearchFilter
 337 {
 338 public:
 339
 340     //------------------------------------------------------------------
 341     /// The basic constructor takes a Target, which gives the space to search,
 342     /// and the module list to restrict the search to.
 343     ///
 344     /// @param[in] target
 345     ///    The Target that provides the module list to search.
 346     ///
 347     /// @param[in] module
 348     ///    The Module that limits the search.
 349     //------------------------------------------------------------------
 350     SearchFilterByModuleList (const lldb::TargetSP &targetSP,
 351                               const FileSpecList &module_list);
 352
 353     SearchFilterByModuleList (const SearchFilterByModuleList& rhs);
 354
 355     virtual
 356     ~SearchFilterByModuleList ();
 357
 358     const SearchFilterByModuleList&
 359     operator=(const SearchFilterByModuleList& rhs);
 360
 361     virtual bool
 362     ModulePasses (const lldb::ModuleSP &module_sp);
 363
 364     virtual bool
 365     ModulePasses (const FileSpec &spec);
 366
 367     virtual bool
 368     AddressPasses (Address &address);
 369
 370     virtual bool
 371     CompUnitPasses (FileSpec &fileSpec);
 372
 373     virtual bool
 374     CompUnitPasses (CompileUnit &compUnit);
 375
 376     virtual void
 377     GetDescription(Stream *s);
 378
 379     virtual uint32_t
 380     GetFilterRequiredItems ();
 381
 382     virtual void
 383     Dump (Stream *s) const;
 384
 385     virtual void
 386     Search (Searcher &searcher);
 387
 388 private:
 389     FileSpecList m_module_spec_list;
 390 };
 391
 392 class SearchFilterByModuleListAndCU :
 393     public SearchFilterByModuleList
 394 {
 395 public:
 396
 397     //------------------------------------------------------------------
 398     /// The basic constructor takes a Target, which gives the space to search,
 399     /// and the module list to restrict the search to.
 400     ///
 401     /// @param[in] target
 402     ///    The Target that provides the module list to search.
 403     ///
 404     /// @param[in] module
 405     ///    The Module that limits the search.
 406     //------------------------------------------------------------------
 407     SearchFilterByModuleListAndCU (const lldb::TargetSP &targetSP,
 408                                    const FileSpecList &module_list,
 409                                    const FileSpecList &cu_list);
 410
 411     SearchFilterByModuleListAndCU (const SearchFilterByModuleListAndCU& rhs);
 412
 413     virtual
 414     ~SearchFilterByModuleListAndCU ();
 415
 416     const SearchFilterByModuleListAndCU&
 417     operator=(const SearchFilterByModuleListAndCU& rhs);
 418
 419     virtual bool
 420     AddressPasses (Address &address);
 421
 422     virtual bool
 423     CompUnitPasses (FileSpec &fileSpec);
 424
 425     virtual bool
 426     CompUnitPasses (CompileUnit &compUnit);
 427
 428     virtual void
 429     GetDescription(Stream *s);
 430
 431     virtual uint32_t
 432     GetFilterRequiredItems ();
 433
 434     virtual void
 435     Dump (Stream *s) const;
 436
 437     virtual void
 438     Search (Searcher &searcher);
 439
 440 private:
 441     FileSpecList m_module_spec_list;
 442     FileSpecList m_cu_spec_list;
 443 };
 444
 445 } // namespace lldb_private
 446
 447 #endif  // liblldb_SearchFilter_h_