contrib/llvm/tools/lldb/include/lldb/Expression/UtilityFunction.h

   1 //===-- UtilityFunction.h ----------------------------------------*- C++
   2 //-*-===//
   3 //
   4 //                     The LLVM Compiler Infrastructure
   5 //
   6 // This file is distributed under the University of Illinois Open Source
   7 // License. See LICENSE.TXT for details.
   8 //
   9 //===----------------------------------------------------------------------===//
  10
  11 #ifndef liblldb_UtilityFunction_h_
  12 #define liblldb_UtilityFunction_h_
  13
  14 #include <memory>
  15 #include <string>
  16
  17 #include "lldb/Expression/Expression.h"
  18 #include "lldb/lldb-forward.h"
  19 #include "lldb/lldb-private.h"
  20
  21 namespace lldb_private {
  22
  23 //----------------------------------------------------------------------
  24 /// @class UtilityFunction UtilityFunction.h
  25 /// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that
  26 /// provides a function that is callable
  27 ///
  28 /// LLDB uses expressions for various purposes, notably to call functions
  29 /// and as a backend for the expr command.  UtilityFunction encapsulates a
  30 /// self-contained function meant to be used from other code.  Utility
  31 /// functions can perform error-checking for ClangUserExpressions,
  32 //----------------------------------------------------------------------
  33 class UtilityFunction : public Expression {
  34 public:
  35   //------------------------------------------------------------------
  36   /// Constructor
  37   ///
  38   /// @param[in] text
  39   ///     The text of the function.  Must be a full translation unit.
  40   ///
  41   /// @param[in] name
  42   ///     The name of the function, as used in the text.
  43   //------------------------------------------------------------------
  44   UtilityFunction(ExecutionContextScope &exe_scope, const char *text,
  45                   const char *name);
  46
  47   ~UtilityFunction() override;
  48
  49   //------------------------------------------------------------------
  50   /// Install the utility function into a process
  51   ///
  52   /// @param[in] diagnostic_manager
  53   ///     A diagnostic manager to print parse errors and warnings to.
  54   ///
  55   /// @param[in] exe_ctx
  56   ///     The execution context to install the utility function to.
  57   ///
  58   /// @return
  59   ///     True on success (no errors); false otherwise.
  60   //------------------------------------------------------------------
  61   virtual bool Install(DiagnosticManager &diagnostic_manager,
  62                        ExecutionContext &exe_ctx) = 0;
  63
  64   //------------------------------------------------------------------
  65   /// Check whether the given PC is inside the function
  66   ///
  67   /// Especially useful if the function dereferences nullptr to indicate a
  68   /// failed assert.
  69   ///
  70   /// @param[in] pc
  71   ///     The program counter to check.
  72   ///
  73   /// @return
  74   ///     True if the program counter falls within the function's bounds;
  75   ///     false if not (or the function is not JIT compiled)
  76   //------------------------------------------------------------------
  77   bool ContainsAddress(lldb::addr_t address) {
  78     // nothing is both >= LLDB_INVALID_ADDRESS and < LLDB_INVALID_ADDRESS, so
  79     // this always returns false if the function is not JIT compiled yet
  80     return (address >= m_jit_start_addr && address < m_jit_end_addr);
  81   }
  82
  83   //------------------------------------------------------------------
  84   /// Return the string that the parser should parse.  Must be a full
  85   /// translation unit.
  86   //------------------------------------------------------------------
  87   const char *Text() override { return m_function_text.c_str(); }
  88
  89   //------------------------------------------------------------------
  90   /// Return the function name that should be used for executing the
  91   /// expression.  Text() should contain the definition of this function.
  92   //------------------------------------------------------------------
  93   const char *FunctionName() override { return m_function_name.c_str(); }
  94
  95   //------------------------------------------------------------------
  96   /// Return the object that the parser should use when registering local
  97   /// variables. May be nullptr if the Expression doesn't care.
  98   //------------------------------------------------------------------
  99   ExpressionVariableList *LocalVariables() { return nullptr; }
 100
 101   //------------------------------------------------------------------
 102   /// Return true if validation code should be inserted into the expression.
 103   //------------------------------------------------------------------
 104   bool NeedsValidation() override { return false; }
 105
 106   //------------------------------------------------------------------
 107   /// Return true if external variables in the expression should be resolved.
 108   //------------------------------------------------------------------
 109   bool NeedsVariableResolution() override { return false; }
 110
 111   // This makes the function caller function. Pass in the ThreadSP if you have
 112   // one available, compilation can end up calling code (e.g. to look up
 113   // indirect functions) and we don't want this to wander onto another thread.
 114   FunctionCaller *MakeFunctionCaller(const CompilerType &return_type,
 115                                      const ValueList &arg_value_list,
 116                                      lldb::ThreadSP compilation_thread,
 117                                      Status &error);
 118
 119   // This one retrieves the function caller that is already made.  If you
 120   // haven't made it yet, this returns nullptr
 121   FunctionCaller *GetFunctionCaller() { return m_caller_up.get(); }
 122
 123 protected:
 124   std::shared_ptr<IRExecutionUnit> m_execution_unit_sp;
 125   lldb::ModuleWP m_jit_module_wp;
 126   std::string m_function_text; ///< The text of the function.  Must be a
 127                                ///well-formed translation unit.
 128   std::string m_function_name; ///< The name of the function.
 129   std::unique_ptr<FunctionCaller> m_caller_up;
 130 };
 131
 132 } // namespace lldb_private
 133
 134 #endif // liblldb_UtilityFunction_h_