ClangUserExpression.h revision 1cf3da8b0fb0cabf2431b5fe521842929fca69a3
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/Expression/IRForTarget.h" 29#include "lldb/Symbol/TaggedASTType.h" 30#include "lldb/Target/ExecutionContext.h" 31 32#include "llvm/ExecutionEngine/JITMemoryManager.h" 33 34namespace lldb_private 35{ 36 37//---------------------------------------------------------------------- 38/// @class ClangUserExpression ClangUserExpression.h "lldb/Expression/ClangUserExpression.h" 39/// @brief Encapsulates a single expression for use with Clang 40/// 41/// LLDB uses expressions for various purposes, notably to call functions 42/// and as a backend for the expr command. ClangUserExpression encapsulates 43/// the objects needed to parse and interpret or JIT an expression. It 44/// uses the Clang parser to produce LLVM IR from the expression. 45//---------------------------------------------------------------------- 46class ClangUserExpression : public ClangExpression 47{ 48public: 49 typedef STD_SHARED_PTR(ClangUserExpression) ClangUserExpressionSP; 50 51 enum { kDefaultTimeout = 500000u }; 52 //------------------------------------------------------------------ 53 /// Constructor 54 /// 55 /// @param[in] expr 56 /// The expression to parse. 57 /// 58 /// @param[in] expr_prefix 59 /// If non-NULL, a C string containing translation-unit level 60 /// definitions to be included when the expression is parsed. 61 /// 62 /// @param[in] language 63 /// If not eLanguageTypeUnknown, a language to use when parsing 64 /// the expression. Currently restricted to those languages 65 /// supported by Clang. 66 /// 67 /// @param[in] desired_type 68 /// If not eResultTypeAny, the type to use for the expression 69 /// result. 70 //------------------------------------------------------------------ 71 ClangUserExpression (const char *expr, 72 const char *expr_prefix, 73 lldb::LanguageType language, 74 ResultType desired_type); 75 76 //------------------------------------------------------------------ 77 /// Destructor 78 //------------------------------------------------------------------ 79 virtual 80 ~ClangUserExpression (); 81 82 //------------------------------------------------------------------ 83 /// Parse the expression 84 /// 85 /// @param[in] error_stream 86 /// A stream to print parse errors and warnings to. 87 /// 88 /// @param[in] exe_ctx 89 /// The execution context to use when looking up entities that 90 /// are needed for parsing (locations of functions, types of 91 /// variables, persistent variables, etc.) 92 /// 93 /// @param[in] execution_policy 94 /// Determines whether interpretation is possible or mandatory. 95 /// 96 /// @param[in] keep_result_in_memory 97 /// True if the resulting persistent variable should reside in 98 /// target memory, if applicable. 99 /// 100 /// @return 101 /// True on success (no errors); false otherwise. 102 //------------------------------------------------------------------ 103 bool 104 Parse (Stream &error_stream, 105 ExecutionContext &exe_ctx, 106 lldb_private::ExecutionPolicy execution_policy, 107 bool keep_result_in_memory); 108 109 //------------------------------------------------------------------ 110 /// Execute the parsed expression 111 /// 112 /// @param[in] error_stream 113 /// A stream to print errors to. 114 /// 115 /// @param[in] exe_ctx 116 /// The execution context to use when looking up entities that 117 /// are needed for parsing (locations of variables, etc.) 118 /// 119 /// @param[in] unwind_on_error 120 /// If true, and the execution stops before completion, we unwind the 121 /// function call, and return the program state to what it was before the 122 /// execution. If false, we leave the program in the stopped state. 123 /// 124 /// @param[in] ignore_breakpoints 125 /// If true, ignore breakpoints while executing the expression. 126 /// 127 /// @param[in] shared_ptr_to_me 128 /// This is a shared pointer to this ClangUserExpression. This is 129 /// needed because Execute can push a thread plan that will hold onto 130 /// the ClangUserExpression for an unbounded period of time. So you 131 /// need to give the thread plan a reference to this object that can 132 /// keep it alive. 133 /// 134 /// @param[in] result 135 /// A pointer to direct at the persistent variable in which the 136 /// expression's result is stored. 137 /// 138 /// @param[in] try_all_threads 139 /// If true, then we will try to run all threads if the function doesn't complete on 140 /// one thread. See timeout_usec for the interaction of this variable and 141 /// the timeout. 142 /// 143 /// @param[in] timeout_usec 144 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 145 /// will try on one thread for the lesser of .25 sec and half the total timeout. 146 /// then switch to running all threads, otherwise this will be the total timeout. 147 /// 148 /// 149 /// @return 150 /// A Process::Execution results value. 151 //------------------------------------------------------------------ 152 ExecutionResults 153 Execute (Stream &error_stream, 154 ExecutionContext &exe_ctx, 155 bool unwind_on_error, 156 bool ignore_breakpoints, 157 ClangUserExpressionSP &shared_ptr_to_me, 158 lldb::ClangExpressionVariableSP &result, 159 bool try_all_threads, 160 uint32_t timeout_usec); 161 162 ThreadPlan * 163 GetThreadPlanToExecuteJITExpression (Stream &error_stream, 164 ExecutionContext &exe_ctx); 165 166 //------------------------------------------------------------------ 167 /// Apply the side effects of the function to program state. 168 /// 169 /// @param[in] error_stream 170 /// A stream to print errors to. 171 /// 172 /// @param[in] exe_ctx 173 /// The execution context to use when looking up entities that 174 /// are needed for parsing (locations of variables, etc.) 175 /// 176 /// @param[in] result 177 /// A pointer to direct at the persistent variable in which the 178 /// expression's result is stored. 179 /// 180 /// @param[in] function_stack_pointer 181 /// A pointer to the base of the function's stack frame. This 182 /// is used to determine whether the expession result resides in 183 /// memory that will still be valid, or whether it needs to be 184 /// treated as homeless for the purpose of future expressions. 185 /// 186 /// @return 187 /// A Process::Execution results value. 188 //------------------------------------------------------------------ 189 bool 190 FinalizeJITExecution (Stream &error_stream, 191 ExecutionContext &exe_ctx, 192 lldb::ClangExpressionVariableSP &result, 193 lldb::addr_t function_stack_pointer = LLDB_INVALID_ADDRESS); 194 195 //------------------------------------------------------------------ 196 /// Return the string that the parser should parse. Must be a full 197 /// translation unit. 198 //------------------------------------------------------------------ 199 const char * 200 Text () 201 { 202 return m_transformed_text.c_str(); 203 } 204 205 //------------------------------------------------------------------ 206 /// Return the string that the user typed. 207 //------------------------------------------------------------------ 208 const char * 209 GetUserText () 210 { 211 return m_expr_text.c_str(); 212 } 213 214 //------------------------------------------------------------------ 215 /// Return the function name that should be used for executing the 216 /// expression. Text() should contain the definition of this 217 /// function. 218 //------------------------------------------------------------------ 219 const char * 220 FunctionName () 221 { 222 return "$__lldb_expr"; 223 } 224 225 //------------------------------------------------------------------ 226 /// Return the language that should be used when parsing. To use 227 /// the default, return eLanguageTypeUnknown. 228 //------------------------------------------------------------------ 229 virtual lldb::LanguageType 230 Language () 231 { 232 return m_language; 233 } 234 235 //------------------------------------------------------------------ 236 /// Return the object that the parser should use when resolving external 237 /// values. May be NULL if everything should be self-contained. 238 //------------------------------------------------------------------ 239 ClangExpressionDeclMap * 240 DeclMap () 241 { 242 return m_expr_decl_map.get(); 243 } 244 245 //------------------------------------------------------------------ 246 /// Return the object that the parser should use when registering 247 /// local variables. May be NULL if the Expression doesn't care. 248 //------------------------------------------------------------------ 249 ClangExpressionVariableList * 250 LocalVariables () 251 { 252 return m_local_variables.get(); 253 } 254 255 //------------------------------------------------------------------ 256 /// Return the object that the parser should allow to access ASTs. 257 /// May be NULL if the ASTs do not need to be transformed. 258 /// 259 /// @param[in] passthrough 260 /// The ASTConsumer that the returned transformer should send 261 /// the ASTs to after transformation. 262 //------------------------------------------------------------------ 263 clang::ASTConsumer * 264 ASTTransformer (clang::ASTConsumer *passthrough); 265 266 //------------------------------------------------------------------ 267 /// Return the desired result type of the function, or 268 /// eResultTypeAny if indifferent. 269 //------------------------------------------------------------------ 270 virtual ResultType 271 DesiredResultType () 272 { 273 return m_desired_type; 274 } 275 276 //------------------------------------------------------------------ 277 /// Return true if validation code should be inserted into the 278 /// expression. 279 //------------------------------------------------------------------ 280 bool 281 NeedsValidation () 282 { 283 return true; 284 } 285 286 //------------------------------------------------------------------ 287 /// Return true if external variables in the expression should be 288 /// resolved. 289 //------------------------------------------------------------------ 290 bool 291 NeedsVariableResolution () 292 { 293 return true; 294 } 295 296 //------------------------------------------------------------------ 297 /// Evaluate one expression and return its result. 298 /// 299 /// @param[in] exe_ctx 300 /// The execution context to use when evaluating the expression. 301 /// 302 /// @param[in] execution_policy 303 /// Determines whether or not to try using the IR interpreter to 304 /// avoid running the expression on the parser. 305 /// 306 /// @param[in] language 307 /// If not eLanguageTypeUnknown, a language to use when parsing 308 /// the expression. Currently restricted to those languages 309 /// supported by Clang. 310 /// 311 /// @param[in] unwind_on_error 312 /// True if the thread's state should be restored in the case 313 /// of an error. 314 /// 315 /// @param[in] ignore_breakpoints 316 /// If true, ignore breakpoints while executing the expression. 317 /// 318 /// @param[in] result_type 319 /// If not eResultTypeAny, the type of the desired result. Will 320 /// result in parse errors if impossible. 321 /// 322 /// @param[in] expr_cstr 323 /// A C string containing the expression to be evaluated. 324 /// 325 /// @param[in] expr_prefix 326 /// If non-NULL, a C string containing translation-unit level 327 /// definitions to be included when the expression is parsed. 328 /// 329 /// @param[in/out] result_valobj_sp 330 /// If execution is successful, the result valobj is placed here. 331 /// 332 /// @param[in] try_all_threads 333 /// If true, then we will try to run all threads if the function doesn't complete on 334 /// one thread. See timeout_usec for the interaction of this variable and 335 /// the timeout. 336 /// 337 /// @param[in] timeout_usec 338 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 339 /// will try on one thread for the lesser of .25 sec and half the total timeout. 340 /// then switch to running all threads, otherwise this will be the total timeout. 341 /// 342 /// @result 343 /// A Process::ExecutionResults value. eExecutionCompleted for success. 344 //------------------------------------------------------------------ 345 static ExecutionResults 346 Evaluate (ExecutionContext &exe_ctx, 347 lldb_private::ExecutionPolicy execution_policy, 348 lldb::LanguageType language, 349 ResultType desired_type, 350 bool unwind_on_error, 351 bool ignore_breakpoints, 352 const char *expr_cstr, 353 const char *expr_prefix, 354 lldb::ValueObjectSP &result_valobj_sp, 355 bool try_all_threads, 356 uint32_t timeout_usec); 357 358 static ExecutionResults 359 EvaluateWithError (ExecutionContext &exe_ctx, 360 lldb_private::ExecutionPolicy execution_policy, 361 lldb::LanguageType language, 362 ResultType desired_type, 363 bool unwind_on_error, 364 bool ignore_breakpoints, 365 const char *expr_cstr, 366 const char *expr_prefix, 367 lldb::ValueObjectSP &result_valobj_sp, 368 Error &error, 369 bool try_all_threads, 370 uint32_t timeout_usec); 371 372 static const Error::ValueType kNoResult = 0x1001; ///< ValueObject::GetError() returns this if there is no result from the expression. 373private: 374 //------------------------------------------------------------------ 375 /// Populate m_cplusplus and m_objetivec based on the environment. 376 //------------------------------------------------------------------ 377 378 void 379 ScanContext (ExecutionContext &exe_ctx, 380 lldb_private::Error &err); 381 382 bool 383 PrepareToExecuteJITExpression (Stream &error_stream, 384 ExecutionContext &exe_ctx, 385 lldb::addr_t &struct_address, 386 lldb::addr_t &object_ptr, 387 lldb::addr_t &cmd_ptr); 388 389 bool 390 EvaluatedStatically () 391 { 392 return m_evaluated_statically; 393 } 394 395 void 396 InstallContext (ExecutionContext &exe_ctx) 397 { 398 m_process_wp = exe_ctx.GetProcessSP(); 399 m_target_wp = exe_ctx.GetTargetSP(); 400 m_frame_wp = exe_ctx.GetFrameSP(); 401 } 402 403 bool 404 LockAndCheckContext (ExecutionContext &exe_ctx, 405 lldb::TargetSP &target_sp, 406 lldb::ProcessSP &process_sp, 407 lldb::StackFrameSP &frame_sp) 408 { 409 target_sp = m_target_wp.lock(); 410 process_sp = m_process_wp.lock(); 411 frame_sp = m_frame_wp.lock(); 412 413 if ((target_sp && target_sp.get() != exe_ctx.GetTargetPtr()) || 414 (process_sp && process_sp.get() != exe_ctx.GetProcessPtr()) || 415 (frame_sp && frame_sp.get() != exe_ctx.GetFramePtr())) 416 return false; 417 418 return true; 419 } 420 421 lldb::TargetWP m_target_wp; ///< The target used as the context for the expression. 422 lldb::ProcessWP m_process_wp; ///< The process used as the context for the expression. 423 lldb::StackFrameWP m_frame_wp; ///< The stack frame used as context for the expression. 424 425 std::string m_expr_text; ///< The text of the expression, as typed by the user 426 std::string m_expr_prefix; ///< The text of the translation-level definitions, as provided by the user 427 lldb::LanguageType m_language; ///< The language to use when parsing (eLanguageTypeUnknown means use defaults) 428 bool m_allow_cxx; ///< True if the language allows C++. 429 bool m_allow_objc; ///< True if the language allows Objective-C. 430 std::string m_transformed_text; ///< The text of the expression, as send to the parser 431 ResultType m_desired_type; ///< The type to coerce the expression's result to. If eResultTypeAny, inferred from the expression. 432 433 std::auto_ptr<ClangExpressionDeclMap> m_expr_decl_map; ///< The map to use when parsing and materializing the expression. 434 std::auto_ptr<ClangExpressionVariableList> m_local_variables; ///< The local expression variables, if the expression is DWARF. 435 436 std::auto_ptr<ASTResultSynthesizer> m_result_synthesizer; ///< The result synthesizer, if one is needed. 437 438 bool m_enforce_valid_object; ///< True if the expression parser should enforce the presence of a valid class pointer in order to generate the expression as a method. 439 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). 440 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). 441 bool m_static_method; ///< True if the expression is compiled as a static (or class) method (currently true if it was parsed when exe_ctx was in an Objective-C class method). 442 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. 443 bool m_const_object; ///< True if "this" is const. 444 Target *m_target; ///< The target for storing persistent data like types and variables. 445 446 bool m_evaluated_statically; ///< True if the expression could be evaluated statically; false otherwise. 447 lldb::ClangExpressionVariableSP m_const_result; ///< The statically-computed result of the expression. NULL if it could not be computed statically or the expression has side effects. 448}; 449 450} // namespace lldb_private 451 452#endif // liblldb_ClangUserExpression_h_ 453