ClangUserExpression.h revision 3b16eb9d424068446fea9cd0e0fe5e7d435f5b6e
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 allow to access ASTs. 247 /// May be NULL if the ASTs do not need to be transformed. 248 /// 249 /// @param[in] passthrough 250 /// The ASTConsumer that the returned transformer should send 251 /// the ASTs to after transformation. 252 //------------------------------------------------------------------ 253 clang::ASTConsumer * 254 ASTTransformer (clang::ASTConsumer *passthrough); 255 256 //------------------------------------------------------------------ 257 /// Return the desired result type of the function, or 258 /// eResultTypeAny if indifferent. 259 //------------------------------------------------------------------ 260 virtual ResultType 261 DesiredResultType () 262 { 263 return m_desired_type; 264 } 265 266 //------------------------------------------------------------------ 267 /// Return true if validation code should be inserted into the 268 /// expression. 269 //------------------------------------------------------------------ 270 bool 271 NeedsValidation () 272 { 273 return true; 274 } 275 276 //------------------------------------------------------------------ 277 /// Return true if external variables in the expression should be 278 /// resolved. 279 //------------------------------------------------------------------ 280 bool 281 NeedsVariableResolution () 282 { 283 return true; 284 } 285 286 //------------------------------------------------------------------ 287 /// Evaluate one expression and return its result. 288 /// 289 /// @param[in] exe_ctx 290 /// The execution context to use when evaluating the expression. 291 /// 292 /// @param[in] execution_policy 293 /// Determines whether or not to try using the IR interpreter to 294 /// avoid running the expression on the parser. 295 /// 296 /// @param[in] language 297 /// If not eLanguageTypeUnknown, a language to use when parsing 298 /// the expression. Currently restricted to those languages 299 /// supported by Clang. 300 /// 301 /// @param[in] unwind_on_error 302 /// True if the thread's state should be restored in the case 303 /// of an error. 304 /// 305 /// @param[in] ignore_breakpoints 306 /// If true, ignore breakpoints while executing the expression. 307 /// 308 /// @param[in] result_type 309 /// If not eResultTypeAny, the type of the desired result. Will 310 /// result in parse errors if impossible. 311 /// 312 /// @param[in] expr_cstr 313 /// A C string containing the expression to be evaluated. 314 /// 315 /// @param[in] expr_prefix 316 /// If non-NULL, a C string containing translation-unit level 317 /// definitions to be included when the expression is parsed. 318 /// 319 /// @param[in/out] result_valobj_sp 320 /// If execution is successful, the result valobj is placed here. 321 /// 322 /// @param[in] try_all_threads 323 /// If true, then we will try to run all threads if the function doesn't complete on 324 /// one thread. See timeout_usec for the interaction of this variable and 325 /// the timeout. 326 /// 327 /// @param[in] timeout_usec 328 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 329 /// will try on one thread for the lesser of .25 sec and half the total timeout. 330 /// then switch to running all threads, otherwise this will be the total timeout. 331 /// 332 /// @result 333 /// A Process::ExecutionResults value. eExecutionCompleted for success. 334 //------------------------------------------------------------------ 335 static ExecutionResults 336 Evaluate (ExecutionContext &exe_ctx, 337 lldb_private::ExecutionPolicy execution_policy, 338 lldb::LanguageType language, 339 ResultType desired_type, 340 bool unwind_on_error, 341 bool ignore_breakpoints, 342 const char *expr_cstr, 343 const char *expr_prefix, 344 lldb::ValueObjectSP &result_valobj_sp, 345 bool try_all_threads, 346 uint32_t timeout_usec); 347 348 static ExecutionResults 349 EvaluateWithError (ExecutionContext &exe_ctx, 350 lldb_private::ExecutionPolicy execution_policy, 351 lldb::LanguageType language, 352 ResultType desired_type, 353 bool unwind_on_error, 354 bool ignore_breakpoints, 355 const char *expr_cstr, 356 const char *expr_prefix, 357 lldb::ValueObjectSP &result_valobj_sp, 358 Error &error, 359 bool try_all_threads, 360 uint32_t timeout_usec); 361 362 static const Error::ValueType kNoResult = 0x1001; ///< ValueObject::GetError() returns this if there is no result from the expression. 363private: 364 //------------------------------------------------------------------ 365 /// Populate m_cplusplus and m_objetivec based on the environment. 366 //------------------------------------------------------------------ 367 368 void 369 ScanContext (ExecutionContext &exe_ctx, 370 lldb_private::Error &err); 371 372 bool 373 PrepareToExecuteJITExpression (Stream &error_stream, 374 ExecutionContext &exe_ctx, 375 lldb::addr_t &struct_address, 376 lldb::addr_t &object_ptr, 377 lldb::addr_t &cmd_ptr); 378 379 bool 380 EvaluatedStatically () 381 { 382 return m_evaluated_statically; 383 } 384 385 void 386 InstallContext (ExecutionContext &exe_ctx) 387 { 388 m_process_wp = exe_ctx.GetProcessSP(); 389 m_target_wp = exe_ctx.GetTargetSP(); 390 m_frame_wp = exe_ctx.GetFrameSP(); 391 } 392 393 bool 394 LockAndCheckContext (ExecutionContext &exe_ctx, 395 lldb::TargetSP &target_sp, 396 lldb::ProcessSP &process_sp, 397 lldb::StackFrameSP &frame_sp) 398 { 399 target_sp = m_target_wp.lock(); 400 process_sp = m_process_wp.lock(); 401 frame_sp = m_frame_wp.lock(); 402 403 if ((target_sp && target_sp.get() != exe_ctx.GetTargetPtr()) || 404 (process_sp && process_sp.get() != exe_ctx.GetProcessPtr()) || 405 (frame_sp && frame_sp.get() != exe_ctx.GetFramePtr())) 406 return false; 407 408 return true; 409 } 410 411 lldb::TargetWP m_target_wp; ///< The target used as the context for the expression. 412 lldb::ProcessWP m_process_wp; ///< The process used as the context for the expression. 413 lldb::StackFrameWP m_frame_wp; ///< The stack frame used as context for the expression. 414 415 std::string m_expr_text; ///< The text of the expression, as typed by the user 416 std::string m_expr_prefix; ///< The text of the translation-level definitions, as provided by the user 417 lldb::LanguageType m_language; ///< The language to use when parsing (eLanguageTypeUnknown means use defaults) 418 bool m_allow_cxx; ///< True if the language allows C++. 419 bool m_allow_objc; ///< True if the language allows Objective-C. 420 std::string m_transformed_text; ///< The text of the expression, as send to the parser 421 ResultType m_desired_type; ///< The type to coerce the expression's result to. If eResultTypeAny, inferred from the expression. 422 423 std::auto_ptr<ClangExpressionDeclMap> m_expr_decl_map; ///< The map to use when parsing the expression. 424 425 std::auto_ptr<IRExecutionUnit> m_execution_unit_ap; ///< The execution unit the expression is stored in. 426 std::auto_ptr<Materializer> m_materializer_ap; ///< The materializer to use when running the expression. 427 428 std::auto_ptr<ASTResultSynthesizer> m_result_synthesizer; ///< The result synthesizer, if one is needed. 429 430 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. 431 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). 432 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). 433 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). 434 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. 435 bool m_const_object; ///< True if "this" is const. 436 Target *m_target; ///< The target for storing persistent data like types and variables. 437 438 bool m_evaluated_statically; ///< True if the expression could be evaluated statically; false otherwise. 439 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. 440}; 441 442} // namespace lldb_private 443 444#endif // liblldb_ClangUserExpression_h_ 445