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