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