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

   1 //===-- UserExpression.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_UserExpression_h_
  11 #define liblldb_UserExpression_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <memory>
  16 #include <string>
  17 #include <vector>
  18
  19 // Other libraries and framework includes
  20 // Project includes
  21 #include "lldb/Core/Address.h"
  22 #include "lldb/Expression/Expression.h"
  23 #include "lldb/Expression/Materializer.h"
  24 #include "lldb/Target/ExecutionContext.h"
  25 #include "lldb/Target/Target.h"
  26 #include "lldb/lldb-forward.h"
  27 #include "lldb/lldb-private.h"
  28
  29 namespace lldb_private {
  30
  31 //----------------------------------------------------------------------
  32 /// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h"
  33 /// @brief Encapsulates a one-time expression for use in lldb.
  34 ///
  35 /// LLDB uses expressions for various purposes, notably to call functions
  36 /// and as a backend for the expr command.  UserExpression is a virtual base
  37 /// class that encapsulates the objects needed to parse and interpret or
  38 /// JIT an expression.  The actual parsing part will be provided by the specific
  39 /// implementations of UserExpression - which will be vended through the
  40 /// appropriate TypeSystem.
  41 //----------------------------------------------------------------------
  42 class UserExpression : public Expression {
  43 public:
  44   enum { kDefaultTimeout = 500000u };
  45
  46   //------------------------------------------------------------------
  47   /// Constructor
  48   ///
  49   /// @param[in] expr
  50   ///     The expression to parse.
  51   ///
  52   /// @param[in] expr_prefix
  53   ///     If non-nullptr, a C string containing translation-unit level
  54   ///     definitions to be included when the expression is parsed.
  55   ///
  56   /// @param[in] language
  57   ///     If not eLanguageTypeUnknown, a language to use when parsing
  58   ///     the expression.  Currently restricted to those languages
  59   ///     supported by Clang.
  60   ///
  61   /// @param[in] desired_type
  62   ///     If not eResultTypeAny, the type to use for the expression
  63   ///     result.
  64   //------------------------------------------------------------------
  65   UserExpression(ExecutionContextScope &exe_scope, llvm::StringRef expr,
  66                  llvm::StringRef prefix, lldb::LanguageType language,
  67                  ResultType desired_type,
  68                  const EvaluateExpressionOptions &options);
  69
  70   //------------------------------------------------------------------
  71   /// Destructor
  72   //------------------------------------------------------------------
  73   ~UserExpression() override;
  74
  75   //------------------------------------------------------------------
  76   /// Parse the expression
  77   ///
  78   /// @param[in] diagnostic_manager
  79   ///     A diagnostic manager to report parse errors and warnings to.
  80   ///
  81   /// @param[in] exe_ctx
  82   ///     The execution context to use when looking up entities that
  83   ///     are needed for parsing (locations of functions, types of
  84   ///     variables, persistent variables, etc.)
  85   ///
  86   /// @param[in] execution_policy
  87   ///     Determines whether interpretation is possible or mandatory.
  88   ///
  89   /// @param[in] keep_result_in_memory
  90   ///     True if the resulting persistent variable should reside in
  91   ///     target memory, if applicable.
  92   ///
  93   /// @return
  94   ///     True on success (no errors); false otherwise.
  95   //------------------------------------------------------------------
  96   virtual bool Parse(DiagnosticManager &diagnostic_manager,
  97                      ExecutionContext &exe_ctx,
  98                      lldb_private::ExecutionPolicy execution_policy,
  99                      bool keep_result_in_memory, bool generate_debug_info) = 0;
 100
 101   virtual bool CanInterpret() = 0;
 102
 103   bool MatchesContext(ExecutionContext &exe_ctx);
 104
 105   //------------------------------------------------------------------
 106   /// Execute the parsed expression by callinng the derived class's
 107   /// DoExecute method.
 108   ///
 109   /// @param[in] diagnostic_manager
 110   ///     A diagnostic manager to report errors to.
 111   ///
 112   /// @param[in] exe_ctx
 113   ///     The execution context to use when looking up entities that
 114   ///     are needed for parsing (locations of variables, etc.)
 115   ///
 116   /// @param[in] options
 117   ///     Expression evaluation options.
 118   ///
 119   /// @param[in] shared_ptr_to_me
 120   ///     This is a shared pointer to this UserExpression.  This is
 121   ///     needed because Execute can push a thread plan that will hold onto
 122   ///     the UserExpression for an unbounded period of time.  So you
 123   ///     need to give the thread plan a reference to this object that can
 124   ///     keep it alive.
 125   ///
 126   /// @param[in] result
 127   ///     A pointer to direct at the persistent variable in which the
 128   ///     expression's result is stored.
 129   ///
 130   /// @return
 131   ///     A Process::Execution results value.
 132   //------------------------------------------------------------------
 133   lldb::ExpressionResults Execute(DiagnosticManager &diagnostic_manager,
 134                                   ExecutionContext &exe_ctx,
 135                                   const EvaluateExpressionOptions &options,
 136                                   lldb::UserExpressionSP &shared_ptr_to_me,
 137                                   lldb::ExpressionVariableSP &result);
 138
 139   //------------------------------------------------------------------
 140   /// Apply the side effects of the function to program state.
 141   ///
 142   /// @param[in] diagnostic_manager
 143   ///     A diagnostic manager to report errors to.
 144   ///
 145   /// @param[in] exe_ctx
 146   ///     The execution context to use when looking up entities that
 147   ///     are needed for parsing (locations of variables, etc.)
 148   ///
 149   /// @param[in] result
 150   ///     A pointer to direct at the persistent variable in which the
 151   ///     expression's result is stored.
 152   ///
 153   /// @param[in] function_stack_pointer
 154   ///     A pointer to the base of the function's stack frame.  This
 155   ///     is used to determine whether the expression result resides in
 156   ///     memory that will still be valid, or whether it needs to be
 157   ///     treated as homeless for the purpose of future expressions.
 158   ///
 159   /// @return
 160   ///     A Process::Execution results value.
 161   //------------------------------------------------------------------
 162   virtual bool FinalizeJITExecution(
 163       DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
 164       lldb::ExpressionVariableSP &result,
 165       lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS,
 166       lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS) = 0;
 167
 168   //------------------------------------------------------------------
 169   /// Return the string that the parser should parse.
 170   //------------------------------------------------------------------
 171   const char *Text() override { return m_expr_text.c_str(); }
 172
 173   //------------------------------------------------------------------
 174   /// Return the string that the user typed.
 175   //------------------------------------------------------------------
 176   const char *GetUserText() { return m_expr_text.c_str(); }
 177
 178   //------------------------------------------------------------------
 179   /// Return the function name that should be used for executing the
 180   /// expression.  Text() should contain the definition of this
 181   /// function.
 182   //------------------------------------------------------------------
 183   const char *FunctionName() override { return "$__lldb_expr"; }
 184
 185   //------------------------------------------------------------------
 186   /// Return the language that should be used when parsing.  To use
 187   /// the default, return eLanguageTypeUnknown.
 188   //------------------------------------------------------------------
 189   lldb::LanguageType Language() override { return m_language; }
 190
 191   //------------------------------------------------------------------
 192   /// Return the desired result type of the function, or
 193   /// eResultTypeAny if indifferent.
 194   //------------------------------------------------------------------
 195   ResultType DesiredResultType() override { return m_desired_type; }
 196
 197   //------------------------------------------------------------------
 198   /// Return true if validation code should be inserted into the
 199   /// expression.
 200   //------------------------------------------------------------------
 201   bool NeedsValidation() override { return true; }
 202
 203   //------------------------------------------------------------------
 204   /// Return true if external variables in the expression should be
 205   /// resolved.
 206   //------------------------------------------------------------------
 207   bool NeedsVariableResolution() override { return true; }
 208
 209   EvaluateExpressionOptions *GetOptions() override { return &m_options; }
 210
 211   virtual lldb::ExpressionVariableSP
 212   GetResultAfterDematerialization(ExecutionContextScope *exe_scope) {
 213     return lldb::ExpressionVariableSP();
 214   }
 215
 216   virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); }
 217
 218   //------------------------------------------------------------------
 219   /// Evaluate one expression in the scratch context of the
 220   /// target passed in the exe_ctx and return its result.
 221   ///
 222   /// @param[in] exe_ctx
 223   ///     The execution context to use when evaluating the expression.
 224   ///
 225   /// @param[in] options
 226   ///     Expression evaluation options.  N.B. The language in the
 227   ///     evaluation options will be used to determine the language used for
 228   ///     expression evaluation.
 229   ///
 230   /// @param[in] expr_cstr
 231   ///     A C string containing the expression to be evaluated.
 232   ///
 233   /// @param[in] expr_prefix
 234   ///     If non-nullptr, a C string containing translation-unit level
 235   ///     definitions to be included when the expression is parsed.
 236   ///
 237   /// @param[in,out] result_valobj_sp
 238   ///      If execution is successful, the result valobj is placed here.
 239   ///
 240   /// @param[out] error
 241   ///     Filled in with an error in case the expression evaluation
 242   ///     fails to parse, run, or evaluated.
 243   ///
 244   /// @param[in] line_offset
 245   ///     The offset of the first line of the expression from the "beginning" of
 246   ///     a virtual source file used for error reporting and debug info.
 247   ///
 248   /// @param[out] fixed_expression
 249   ///     If non-nullptr, the fixed expression is copied into the provided
 250   ///     string.
 251   ///
 252   /// @param[out] jit_module_sp_ptr
 253   ///     If non-nullptr, used to persist the generated IR module.
 254   ///
 255   /// @result
 256   ///      A Process::ExpressionResults value.  eExpressionCompleted for
 257   ///      success.
 258   //------------------------------------------------------------------
 259   static lldb::ExpressionResults
 260   Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options,
 261            llvm::StringRef expr_cstr, llvm::StringRef expr_prefix,
 262            lldb::ValueObjectSP &result_valobj_sp, Status &error,
 263            uint32_t line_offset = 0, std::string *fixed_expression = nullptr,
 264            lldb::ModuleSP *jit_module_sp_ptr = nullptr);
 265
 266   static const Status::ValueType kNoResult =
 267       0x1001; ///< ValueObject::GetError() returns this if there is no result
 268               /// from the expression.
 269
 270   const char *GetFixedText() {
 271     if (m_fixed_text.empty())
 272       return nullptr;
 273     return m_fixed_text.c_str();
 274   }
 275
 276 protected:
 277   virtual lldb::ExpressionResults
 278   DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
 279             const EvaluateExpressionOptions &options,
 280             lldb::UserExpressionSP &shared_ptr_to_me,
 281             lldb::ExpressionVariableSP &result) = 0;
 282
 283   static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp,
 284                                        ConstString &object_name, Status &err);
 285
 286   //------------------------------------------------------------------
 287   /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
 288   /// environment.
 289   //------------------------------------------------------------------
 290
 291   void InstallContext(ExecutionContext &exe_ctx);
 292
 293   bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp,
 294                            lldb::ProcessSP &process_sp,
 295                            lldb::StackFrameSP &frame_sp);
 296
 297   Address m_address;       ///< The address the process is stopped in.
 298   std::string m_expr_text; ///< The text of the expression, as typed by the user
 299   std::string m_expr_prefix; ///< The text of the translation-level definitions,
 300                              ///as provided by the user
 301   std::string m_fixed_text; ///< The text of the expression with fix-its applied
 302                             ///- this won't be set if the fixed text doesn't
 303                             ///parse.
 304   lldb::LanguageType m_language; ///< The language to use when parsing
 305                                  ///(eLanguageTypeUnknown means use defaults)
 306   ResultType m_desired_type; ///< The type to coerce the expression's result to.
 307                              ///If eResultTypeAny, inferred from the expression.
 308   EvaluateExpressionOptions
 309       m_options; ///< Additional options provided by the user.
 310 };
 311
 312 } // namespace lldb_private
 313
 314 #endif // liblldb_UserExpression_h_