Coverage Report

Created: 2023-11-11 10:31

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Expression/UserExpression.h
Line
Count
Source (jump to first uncovered line)
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 LLDB_EXPRESSION_USEREXPRESSION_H
10
#define LLDB_EXPRESSION_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
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
  /// LLVM RTTI support.
37
  static char ID;
38
39
public:
40
0
  bool isA(const void *ClassID) const override { return ClassID == &ID; }
41
0
  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
0
                        unsigned complete_pos) {
113
0
    return false;
114
0
  }
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
0
  const char *Text() override { return m_expr_text.c_str(); }
187
188
  /// Return the string that the user typed.
189
85
  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
6.88k
  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
21.4k
  lldb::LanguageType Language() const override { return m_language; }
198
199
  /// Return the desired result type of the function, or eResultTypeAny if
200
  /// indifferent.
201
7.24k
  ResultType DesiredResultType() override { return m_desired_type; }
202
203
  /// Return true if validation code should be inserted into the expression.
204
1.18k
  bool NeedsValidation() override { return true; }
205
206
  /// Return true if external variables in the expression should be resolved.
207
6.91k
  bool NeedsVariableResolution() override { return true; }
208
209
0
  EvaluateExpressionOptions *GetOptions() override { return &m_options; }
210
211
  virtual lldb::ExpressionVariableSP
212
0
  GetResultAfterDematerialization(ExecutionContextScope *exe_scope) {
213
0
    return lldb::ExpressionVariableSP();
214
0
  }
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[in] ctx_obj
246
  ///     If specified, then the expression will be evaluated in the context of
247
  ///     this object. It means that the context object's address will be
248
  ///     treated as `this` for the expression (the expression will be
249
  ///     evaluated as if it was inside of a method of the context object's
250
  ///     class, and its `this` parameter were pointing to the context object).
251
  ///     The parameter makes sense for class and union types only.
252
  ///     Currently there is a limitation: the context object must be located
253
  ///     in the debuggee process' memory (and have the load address).
254
  ///
255
  /// \result
256
  ///      A Process::ExpressionResults value.  eExpressionCompleted for
257
  ///      success.
258
  static lldb::ExpressionResults
259
  Evaluate(ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options,
260
           llvm::StringRef expr_cstr, llvm::StringRef expr_prefix,
261
           lldb::ValueObjectSP &result_valobj_sp, Status &error,
262
           std::string *fixed_expression = nullptr,
263
           ValueObject *ctx_obj = nullptr);
264
265
  static const Status::ValueType kNoResult =
266
      0x1001; ///< ValueObject::GetError() returns this if there is no result
267
              /// from the expression.
268
269
7.13k
  llvm::StringRef GetFixedText() {
270
7.13k
    return m_fixed_text;
271
7.13k
  }
272
273
protected:
274
  virtual lldb::ExpressionResults
275
  DoExecute(DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx,
276
            const EvaluateExpressionOptions &options,
277
            lldb::UserExpressionSP &shared_ptr_to_me,
278
            lldb::ExpressionVariableSP &result) = 0;
279
280
  static lldb::addr_t GetObjectPointer(lldb::StackFrameSP frame_sp,
281
                                       llvm::StringRef object_name,
282
                                       Status &err);
283
284
  /// Return ValueObject for a given variable name in the current stack frame
285
  ///
286
  /// \param[in] frame Current stack frame. When passed a 'nullptr', this
287
  ///                  function returns an empty ValueObjectSP.
288
  ///
289
  /// \param[in] object_name Name of the variable in the current stack frame
290
  ///                        for which we want the ValueObjectSP.
291
  ///
292
  /// \param[out] err Status object which will get set on error.
293
  ///
294
  /// \returns On success returns a ValueObjectSP corresponding to the variable
295
  ///          with 'object_name' in the current 'frame'. Otherwise, returns
296
  ///          'nullptr' (and sets the error status parameter 'err').
297
  static lldb::ValueObjectSP
298
  GetObjectPointerValueObject(lldb::StackFrameSP frame,
299
                              llvm::StringRef object_name, Status &err);
300
301
  /// Populate m_in_cplusplus_method and m_in_objectivec_method based on the
302
  /// environment.
303
304
  void InstallContext(ExecutionContext &exe_ctx);
305
306
  bool LockAndCheckContext(ExecutionContext &exe_ctx, lldb::TargetSP &target_sp,
307
                           lldb::ProcessSP &process_sp,
308
                           lldb::StackFrameSP &frame_sp);
309
310
  Address m_address;       ///< The address the process is stopped in.
311
  std::string m_expr_text; ///< The text of the expression, as typed by the user
312
  std::string m_expr_prefix; ///< The text of the translation-level definitions,
313
                             ///as provided by the user
314
  std::string m_fixed_text; ///< The text of the expression with fix-its applied
315
                            ///- this won't be set if the fixed text doesn't
316
                            ///parse.
317
  lldb::LanguageType m_language; ///< The language to use when parsing
318
                                 ///(eLanguageTypeUnknown means use defaults)
319
  ResultType m_desired_type; ///< The type to coerce the expression's result to.
320
                             ///If eResultTypeAny, inferred from the expression.
321
  EvaluateExpressionOptions
322
      m_options; ///< Additional options provided by the user.
323
};
324
325
} // namespace lldb_private
326
327
#endif // LLDB_EXPRESSION_USEREXPRESSION_H