ClangUserExpression.h revision 427f290ff96f3ab9f2cf3a1af7001d2c560424c7 
1//===-- ClangUserExpression.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_ClangUserExpression_h_
11#define liblldb_ClangUserExpression_h_
12
13// C Includes
14// C++ Includes
15#include <string>
16#include <map>
17#include <memory>
18#include <vector>
19
20// Other libraries and framework includes
21// Project includes
22
23#include "lldb/lldb-forward.h"
24#include "lldb/lldb-private.h"
25#include "lldb/Core/ClangForward.h"
26#include "lldb/Expression/ClangExpression.h"
27#include "lldb/Expression/ClangExpressionVariable.h"
28#include "lldb/Symbol/TaggedASTType.h"
29#include "lldb/Target/Process.h"
30
31#include "llvm/ExecutionEngine/JITMemoryManager.h"
32
33namespace lldb_private
34{
35
36//----------------------------------------------------------------------
37/// @class ClangUserExpression ClangUserExpression.h "lldb/Expression/ClangUserExpression.h"
38/// @brief Encapsulates a single expression for use with Clang
39///
40/// LLDB uses expressions for various purposes, notably to call functions
41/// and as a backend for the expr command.  ClangUserExpression encapsulates
42/// the objects needed to parse and interpret or JIT an expression.  It
43/// uses the Clang parser to produce LLVM IR from the expression.
44//----------------------------------------------------------------------
45class ClangUserExpression : public ClangExpression
46{
47public:
48    typedef lldb::SharedPtr<ClangUserExpression>::Type ClangUserExpressionSP;
49
50    //------------------------------------------------------------------
51    /// Constructor
52    ///
53    /// @param[in] expr
54    ///     The expression to parse.
55    ///
56    /// @param[in] expr_prefix
57    ///     If non-NULL, a C string containing translation-unit level
58    ///     definitions to be included when the expression is parsed.
59    //------------------------------------------------------------------
60    ClangUserExpression (const char *expr,
61                         const char *expr_prefix);
62
63    //------------------------------------------------------------------
64    /// Destructor
65    //------------------------------------------------------------------
66    virtual
67    ~ClangUserExpression ();
68
69    //------------------------------------------------------------------
70    /// Parse the expression
71    ///
72    /// @param[in] error_stream
73    ///     A stream to print 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] desired_type
81    ///     The type that the expression should be coerced to.  If NULL,
82    ///     inferred from the expression itself.
83    ///
84    /// @return
85    ///     True on success (no errors); false otherwise.
86    //------------------------------------------------------------------
87    bool
88    Parse (Stream &error_stream,
89           ExecutionContext &exe_ctx,
90           TypeFromUser desired_type);
91
92    //------------------------------------------------------------------
93    /// Execute the parsed expression
94    ///
95    /// @param[in] error_stream
96    ///     A stream to print errors to.
97    ///
98    /// @param[in] exe_ctx
99    ///     The execution context to use when looking up entities that
100    ///     are needed for parsing (locations of variables, etc.)
101    ///
102    /// @param[in] discard_on_error
103    ///     If true, and the execution stops before completion, we unwind the
104    ///     function call, and return the program state to what it was before the
105    ///     execution.  If false, we leave the program in the stopped state.
106    /// @param[in] shared_ptr_to_me
107    ///     This is a shared pointer to this ClangUserExpression.  This is
108    ///     needed because Execute can push a thread plan that will hold onto
109    ///     the ClangUserExpression for an unbounded period of time.  So you
110    ///     need to give the thread plan a reference to this object that can
111    ///     keep it alive.
112    ///
113    /// @param[in] result
114    ///     A pointer to direct at the persistent variable in which the
115    ///     expression's result is stored.
116    ///
117    /// @return
118    ///     A Process::Execution results value.
119    //------------------------------------------------------------------
120    lldb::ExecutionResults
121    Execute (Stream &error_stream,
122             ExecutionContext &exe_ctx,
123             bool discard_on_error,
124             ClangUserExpressionSP &shared_ptr_to_me,
125             lldb::ClangExpressionVariableSP &result);
126
127    ThreadPlan *
128    GetThreadPlanToExecuteJITExpression (Stream &error_stream,
129                                         ExecutionContext &exe_ctx);
130    bool
131    FinalizeJITExecution (Stream &error_stream,
132                          ExecutionContext &exe_ctx,
133                          lldb::ClangExpressionVariableSP &result);
134
135    //------------------------------------------------------------------
136    /// Return the string that the parser should parse.  Must be a full
137    /// translation unit.
138    //------------------------------------------------------------------
139    const char *
140    Text ()
141    {
142        return m_transformed_text.c_str();
143    }
144
145    //------------------------------------------------------------------
146    /// Return the string that the user typed.
147    //------------------------------------------------------------------
148    const char *
149    GetUserText ()
150    {
151        return m_expr_text.c_str();
152    }
153
154    //------------------------------------------------------------------
155    /// Return the function name that should be used for executing the
156    /// expression.  Text() should contain the definition of this
157    /// function.
158    //------------------------------------------------------------------
159    const char *
160    FunctionName ()
161    {
162        return "$__lldb_expr";
163    }
164
165    //------------------------------------------------------------------
166    /// Return the object that the parser should use when resolving external
167    /// values.  May be NULL if everything should be self-contained.
168    //------------------------------------------------------------------
169    ClangExpressionDeclMap *
170    DeclMap ()
171    {
172        return m_expr_decl_map.get();
173    }
174
175    //------------------------------------------------------------------
176    /// Return the object that the parser should use when registering
177    /// local variables.  May be NULL if the Expression doesn't care.
178    //------------------------------------------------------------------
179    ClangExpressionVariableList *
180    LocalVariables ()
181    {
182        return m_local_variables.get();
183    }
184
185    //------------------------------------------------------------------
186    /// Return the object that the parser should allow to access ASTs.
187    /// May be NULL if the ASTs do not need to be transformed.
188    ///
189    /// @param[in] passthrough
190    ///     The ASTConsumer that the returned transformer should send
191    ///     the ASTs to after transformation.
192    //------------------------------------------------------------------
193    clang::ASTConsumer *
194    ASTTransformer (clang::ASTConsumer *passthrough);
195
196    //------------------------------------------------------------------
197    /// Return the stream that the parser should use to write DWARF
198    /// opcodes.
199    //------------------------------------------------------------------
200    StreamString &
201    DwarfOpcodeStream ();
202
203    //------------------------------------------------------------------
204    /// Return true if validation code should be inserted into the
205    /// expression.
206    //------------------------------------------------------------------
207    bool
208    NeedsValidation ()
209    {
210        return true;
211    }
212
213    //------------------------------------------------------------------
214    /// Return true if external variables in the expression should be
215    /// resolved.
216    //------------------------------------------------------------------
217    bool
218    NeedsVariableResolution ()
219    {
220        return true;
221    }
222
223    //------------------------------------------------------------------
224    /// Evaluate one expression and return its result.
225    ///
226    /// @param[in] exe_ctx
227    ///     The execution context to use when evaluating the expression.
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-NULL, 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    /// @result
240    ///      A Process::ExecutionResults value.  eExecutionCompleted for success.
241    //------------------------------------------------------------------
242    static lldb::ExecutionResults
243    Evaluate (ExecutionContext &exe_ctx,
244              bool discard_on_error,
245              const char *expr_cstr,
246              const char *expr_prefix,
247              lldb::ValueObjectSP &result_valobj_sp);
248
249private:
250    //------------------------------------------------------------------
251    /// Populate m_cplusplus and m_objetivec based on the environment.
252    //------------------------------------------------------------------
253    void
254    ScanContext(ExecutionContext &exe_ctx);
255
256    bool
257    PrepareToExecuteJITExpression (Stream &error_stream,
258                                   ExecutionContext &exe_ctx,
259                                   lldb::addr_t &struct_address,
260                                   lldb::addr_t &object_ptr,
261                                   lldb::addr_t &cmd_ptr);
262
263    std::string                                 m_expr_text;            ///< The text of the expression, as typed by the user
264    std::string                                 m_expr_prefix;          ///< The text of the translation-level definitions, as provided by the user
265    std::string                                 m_transformed_text;     ///< The text of the expression, as send to the parser
266    TypeFromUser                                m_desired_type;         ///< The type to coerce the expression's result to.  If NULL, inferred from the expression.
267
268    std::auto_ptr<ClangExpressionDeclMap>       m_expr_decl_map;        ///< The map to use when parsing and materializing the expression.
269    std::auto_ptr<ClangExpressionVariableList> m_local_variables;      ///< The local expression variables, if the expression is DWARF.
270    std::auto_ptr<StreamString>                 m_dwarf_opcodes;        ///< The DWARF opcodes for the expression.  May be NULL.
271    lldb::addr_t                                m_jit_addr;             ///< The address of the JITted code.  LLDB_INVALID_ADDRESS if invalid.
272
273    bool                                        m_cplusplus;            ///< True if the expression is compiled as a C++ member function (true if it was parsed when exe_ctx was in a C++ method).
274    bool                                        m_objectivec;           ///< True if the expression is compiled as an Objective-C method (true if it was parsed when exe_ctx was in an Objective-C method).
275    bool                                        m_needs_object_ptr;     ///< True if "this" or "self" must be looked up and passed in.  False if the expression doesn't really use them and they can be NULL.
276    bool                                        m_const_object;         ///< True if "this" is const.
277};
278
279} // namespace lldb_private
280
281#endif  // liblldb_ClangUserExpression_h_
282