LLDB  mainline
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Private Attributes | List of all members
lldb_private::UserExpression Class Referenceabstract

Encapsulates a one-time expression for use in lldb. More...

#include "lldb/Expression/UserExpression.h"

Inheritance diagram for lldb_private::UserExpression:
Inheritance graph
[legend]
Collaboration diagram for lldb_private::UserExpression:
Collaboration graph
[legend]

Public Types

enum  { kDefaultTimeout = 500000u }
 
- Public Types inherited from lldb_private::Expression
enum  ResultType { eResultTypeAny, eResultTypeId }
 

Public Member Functions

bool isA (const void *ClassID) const override
 
 UserExpression (ExecutionContextScope &exe_scope, llvm::StringRef expr, llvm::StringRef prefix, lldb::LanguageType language, ResultType desired_type, const EvaluateExpressionOptions &options)
 Constructor. More...
 
 ~UserExpression () override
 Destructor. More...
 
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. More...
 
virtual bool Complete (ExecutionContext &exe_ctx, CompletionRequest &request, unsigned complete_pos)
 Attempts to find possible command line completions for the given (possible incomplete) user expression. More...
 
virtual bool CanInterpret ()=0
 
bool MatchesContext (ExecutionContext &exe_ctx)
 
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's DoExecute method. More...
 
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. More...
 
const char * Text () override
 Return the string that the parser should parse. More...
 
const char * GetUserText ()
 Return the string that the user typed. More...
 
const char * FunctionName () override
 Return the function name that should be used for executing the expression. More...
 
lldb::LanguageType Language () const override
 Return the language that should be used when parsing. More...
 
ResultType DesiredResultType () override
 Return the desired result type of the function, or eResultTypeAny if indifferent. More...
 
bool NeedsValidation () override
 Return true if validation code should be inserted into the expression. More...
 
bool NeedsVariableResolution () override
 Return true if external variables in the expression should be resolved. More...
 
EvaluateExpressionOptionsGetOptions () override
 
virtual lldb::ExpressionVariableSP GetResultAfterDematerialization (ExecutionContextScope *exe_scope)
 
const char * GetFixedText ()
 
- Public Member Functions inherited from lldb_private::Expression
 Expression (Target &target)
 
 Expression (ExecutionContextScope &exe_scope)
 
virtual ~Expression ()
 Destructor. More...
 
virtual MaterializerGetMaterializer ()
 Return the Materializer that the parser should use when registering external values. More...
 
lldb::addr_t StartAddress ()
 Return the address of the function's JIT-compiled code, or LLDB_INVALID_ADDRESS if the function is not JIT compiled. More...
 
virtual void WillStartExecuting ()
 Called to notify the expression that it is about to be executed. More...
 
virtual void DidFinishExecuting ()
 Called to notify the expression that its execution has finished. More...
 
virtual ExpressionTypeSystemHelperGetTypeSystemHelper ()
 

Static Public Member Functions

static bool classof (const Expression *obj)
 
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, ValueObject *ctx_obj=nullptr)
 Evaluate one expression in the scratch context of the target passed in the exe_ctx and return its result. More...
 

Static Public Attributes

static const Status::ValueType kNoResult
 ValueObject::GetError() returns this if there is no result from the expression. More...
 

Protected Member Functions

virtual lldb::ExpressionResults DoExecute (DiagnosticManager &diagnostic_manager, ExecutionContext &exe_ctx, const EvaluateExpressionOptions &options, lldb::UserExpressionSP &shared_ptr_to_me, lldb::ExpressionVariableSP &result)=0
 
void InstallContext (ExecutionContext &exe_ctx)
 Populate m_in_cplusplus_method and m_in_objectivec_method based on the environment. More...
 
bool LockAndCheckContext (ExecutionContext &exe_ctx, lldb::TargetSP &target_sp, lldb::ProcessSP &process_sp, lldb::StackFrameSP &frame_sp)
 

Static Protected Member Functions

static lldb::addr_t GetObjectPointer (lldb::StackFrameSP frame_sp, ConstString &object_name, Status &err)
 

Protected Attributes

Address m_address
 The address the process is stopped in. More...
 
std::string m_expr_text
 The text of the expression, as typed by the user. More...
 
std::string m_expr_prefix
 The text of the translation-level definitions, as provided by the user. More...
 
std::string m_fixed_text
 The text of the expression with fix-its applied. More...
 
lldb::LanguageType m_language
 The language to use when parsing (eLanguageTypeUnknown means use defaults) More...
 
ResultType m_desired_type
 The type to coerce the expression's result to. More...
 
EvaluateExpressionOptions m_options
 Additional options provided by the user. More...
 
- Protected Attributes inherited from lldb_private::Expression
lldb::TargetWP m_target_wp
 
lldb::ProcessWP m_jit_process_wp
 Expression's always have to have a target... More...
 
lldb::addr_t m_jit_start_addr
 An expression might have a process, but it doesn't need to (e.g. More...
 
lldb::addr_t m_jit_end_addr
 The address of the JITted function within the JIT allocation. More...
 

Static Private Attributes

static char ID
 LLVM RTTI support. More...
 

Detailed Description

Encapsulates a one-time expression for use in lldb.

LLDB uses expressions for various purposes, notably to call functions and as a backend for the expr command. UserExpression is a virtual base class that encapsulates the objects needed to parse and interpret or JIT an expression. The actual parsing part will be provided by the specific implementations of UserExpression - which will be vended through the appropriate TypeSystem.

Definition at line 35 of file UserExpression.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
Enumerator
kDefaultTimeout 

Definition at line 43 of file UserExpression.h.

Constructor & Destructor Documentation

◆ UserExpression()

UserExpression::UserExpression ( ExecutionContextScope exe_scope,
llvm::StringRef  expr,
llvm::StringRef  prefix,
lldb::LanguageType  language,
ResultType  desired_type,
const EvaluateExpressionOptions options 
)

Constructor.

Parameters
[in]exprThe expression to parse.
[in]languageIf not eLanguageTypeUnknown, a language to use when parsing the expression. Currently restricted to those languages supported by Clang.
[in]desired_typeIf not eResultTypeAny, the type to use for the expression result.

Definition at line 51 of file UserExpression.cpp.

◆ ~UserExpression()

UserExpression::~UserExpression ( )
override

Destructor.

Definition at line 60 of file UserExpression.cpp.

Member Function Documentation

◆ CanInterpret()

virtual bool lldb_private::UserExpression::CanInterpret ( )
pure virtual

Implemented in lldb_private::LLVMUserExpression.

Referenced by Complete().

◆ classof()

static bool lldb_private::UserExpression::classof ( const Expression obj)
inlinestatic

Definition at line 41 of file UserExpression.h.

References lldb_private::Expression::isA().

◆ Complete()

virtual bool lldb_private::UserExpression::Complete ( ExecutionContext exe_ctx,
CompletionRequest request,
unsigned  complete_pos 
)
inlinevirtual

Attempts to find possible command line completions for the given (possible incomplete) user expression.

Parameters
[in]exe_ctxThe execution context to use when looking up entities that are needed for parsing and completing (locations of functions, types of variables, persistent variables, etc.)
[out]requestThe completion request to fill out. The completion should be a string that would complete the current token at the cursor position. Note that the string in the list replaces the current token in the command line.
[in]complete_posThe position of the cursor inside the user expression string. The completion process starts on the token that the cursor is in.
Returns
True if we added any completion results to the output; false otherwise.

Reimplemented in lldb_private::ClangUserExpression.

Definition at line 111 of file UserExpression.h.

References CanInterpret(), Execute(), FinalizeJITExecution(), LLDB_INVALID_ADDRESS, and MatchesContext().

◆ DesiredResultType()

ResultType lldb_private::UserExpression::DesiredResultType ( )
inlineoverridevirtual

Return the desired result type of the function, or eResultTypeAny if indifferent.

Reimplemented from lldb_private::Expression.

Definition at line 201 of file UserExpression.h.

References m_desired_type.

◆ DoExecute()

virtual lldb::ExpressionResults lldb_private::UserExpression::DoExecute ( DiagnosticManager diagnostic_manager,
ExecutionContext exe_ctx,
const EvaluateExpressionOptions options,
lldb::UserExpressionSP &  shared_ptr_to_me,
lldb::ExpressionVariableSP &  result 
)
protectedpure virtual

Implemented in lldb_private::LLVMUserExpression.

Referenced by Execute(), and GetFixedText().

◆ Evaluate()

lldb::ExpressionResults UserExpression::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,
ValueObject ctx_obj = nullptr 
)
static

Evaluate one expression in the scratch context of the target passed in the exe_ctx and return its result.

Parameters
[in]exe_ctxThe execution context to use when evaluating the expression.
[in]optionsExpression evaluation options. N.B. The language in the evaluation options will be used to determine the language used for expression evaluation.
[in]expr_cstrA C string containing the expression to be evaluated.
[in]expr_prefixIf non-nullptr, a C string containing translation-unit level definitions to be included when the expression is parsed.
[in,out]result_valobj_spIf execution is successful, the result valobj is placed here.
[out]errorFilled in with an error in case the expression evaluation fails to parse, run, or evaluated.
[out]fixed_expressionIf non-nullptr, the fixed expression is copied into the provided string.
[in]ctx_objIf specified, then the expression will be evaluated in the context of this object. It means that the context object's address will be treated as this for the expression (the expression will be evaluated as if it was inside of a method of the context object's class, and its this parameter were pointing to the context object). The parameter makes sense for class and union types only. Currently there is a limitation: the context object must be located in the debuggee process' memory (and have the load address).
Returns
A Process::ExpressionResults value. eExpressionCompleted for success.

Definition at line 143 of file UserExpression.cpp.

References lldb_private::Status::AsCString(), lldb_private::Process::CanJIT(), lldb_private::DiagnosticManager::Clear(), lldb_private::ValueObjectConstResult::Create(), lldb_private::DiagnosticManager::Diagnostics(), lldb_private::EvaluateExpressionOptions::DoesCoerceToId(), lldb::eErrorTypeGeneric, lldb_private::eExecutionPolicyAlways, lldb_private::eExecutionPolicyNever, lldb_private::eExecutionPolicyTopLevel, lldb::eExpressionCompleted, lldb::eExpressionEvaluationComplete, lldb::eExpressionEvaluationExecution, lldb::eExpressionEvaluationParse, lldb::eExpressionInterrupted, lldb::eExpressionParseError, lldb::eExpressionSetupError, lldb::eLanguageTypeUnknown, lldb_private::Expression::eResultTypeAny, lldb_private::Expression::eResultTypeId, error(), lldb::eStateStopped, lldb_private::Status::Fail(), lldb_private::EvaluateExpressionOptions::GetAutoApplyFixIts(), lldb_private::ExecutionContext::GetBestExecutionContextScope(), lldb_private::TargetProperties::GetEnableNotifyAboutFixIts(), lldb_private::EvaluateExpressionOptions::GetExecutionPolicy(), lldb_private::ExecutionContext::GetFramePtr(), lldb_private::EvaluateExpressionOptions::GetGenerateDebugInfo(), lldb_private::TargetProperties::GetLanguage(), lldb_private::EvaluateExpressionOptions::GetLanguage(), lldb_private::GetLogIfAnyCategoriesSet(), lldb_private::EvaluateExpressionOptions::GetPrefix(), lldb_private::ExecutionContext::GetProcessPtr(), lldb_private::EvaluateExpressionOptions::GetRetriesWithFixIts(), lldb_private::Process::GetState(), lldb_private::DiagnosticManager::GetString(), lldb_private::ExecutionContext::GetTargetPtr(), lldb_private::ExecutionContext::GetThreadSP(), lldb_private::ValueObject::GetTypeInfo(), lldb_private::Target::GetUserExpressionForLanguage(), lldb_private::EvaluateExpressionOptions::InvokeCancelCallback(), kNoResult, LIBLLDB_LOG_EXPRESSIONS, LIBLLDB_LOG_STEP, LLDB_LOG, lldb_private::Status::SetError(), lldb_private::Status::SetErrorString(), lldb_private::Status::SetExpressionError(), and lldb_private::Status::SetExpressionErrorWithFormat().

Referenced by lldb_private::Target::EvaluateExpression(), GetResultAfterDematerialization(), lldb_private::REPL::IOHandlerInputComplete(), and lldb_private::StopInfoWatchpoint::PerformAction().

◆ Execute()

lldb::ExpressionResults UserExpression::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's DoExecute method.

Parameters
[in]diagnostic_managerA diagnostic manager to report errors to.
[in]exe_ctxThe execution context to use when looking up entities that are needed for parsing (locations of variables, etc.)
[in]optionsExpression evaluation options.
[in]shared_ptr_to_meThis is a shared pointer to this UserExpression. This is needed because Execute can push a thread plan that will hold onto the UserExpression for an unbounded period of time. So you need to give the thread plan a reference to this object that can keep it alive.
[in]resultA pointer to direct at the persistent variable in which the expression's result is stored.
Returns
A Process::Execution results value.

Definition at line 392 of file UserExpression.cpp.

References DoExecute(), lldb_private::Target::GetPersistentExpressionStateForLanguage(), lldb_private::EvaluateExpressionOptions::GetResultIsInternal(), lldb_private::ExecutionContext::GetTargetPtr(), and m_language.

Referenced by Complete().

◆ FinalizeJITExecution()

virtual bool lldb_private::UserExpression::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 
)
pure virtual

Apply the side effects of the function to program state.

Parameters
[in]diagnostic_managerA diagnostic manager to report errors to.
[in]exe_ctxThe execution context to use when looking up entities that are needed for parsing (locations of variables, etc.)
[in]resultA pointer to direct at the persistent variable in which the expression's result is stored.
[in]function_stack_bottomA pointer to the bottom of the function's stack frame. This is used to determine whether the expression result resides in memory that will still be valid, or whether it needs to be treated as homeless for the purpose of future expressions.
[in]function_stack_topA pointer to the top of the function's stack frame. This is used to determine whether the expression result resides in memory that will still be valid, or whether it needs to be treated as homeless for the purpose of future expressions.
Returns
A Process::Execution results value.

Implemented in lldb_private::LLVMUserExpression.

Referenced by Complete().

◆ FunctionName()

const char* lldb_private::UserExpression::FunctionName ( )
inlineoverridevirtual

Return the function name that should be used for executing the expression.

Text() should contain the definition of this function.

Implements lldb_private::Expression.

Definition at line 193 of file UserExpression.h.

Referenced by lldb_private::ClangUserExpression::Parse().

◆ GetFixedText()

const char* lldb_private::UserExpression::GetFixedText ( )
inline

◆ GetObjectPointer()

lldb::addr_t UserExpression::GetObjectPointer ( lldb::StackFrameSP  frame_sp,
ConstString object_name,
Status err 
)
staticprotected

◆ GetOptions()

EvaluateExpressionOptions* lldb_private::UserExpression::GetOptions ( )
inlineoverridevirtual

Reimplemented from lldb_private::Expression.

Definition at line 209 of file UserExpression.h.

References m_options.

◆ GetResultAfterDematerialization()

virtual lldb::ExpressionVariableSP lldb_private::UserExpression::GetResultAfterDematerialization ( ExecutionContextScope exe_scope)
inlinevirtual

Reimplemented in lldb_private::ClangUserExpression.

Definition at line 212 of file UserExpression.h.

References error(), and Evaluate().

Referenced by lldb_private::LLVMUserExpression::FinalizeJITExecution().

◆ GetUserText()

const char* lldb_private::UserExpression::GetUserText ( )
inline

Return the string that the user typed.

Definition at line 189 of file UserExpression.h.

References m_expr_text.

Referenced by lldb_private::ClangExpressionParser::Complete().

◆ InstallContext()

void UserExpression::InstallContext ( ExecutionContext exe_ctx)
protected

Populate m_in_cplusplus_method and m_in_objectivec_method based on the environment.

Definition at line 62 of file UserExpression.cpp.

References lldb_private::ExecutionContext::GetFrameSP(), lldb_private::ExecutionContext::GetProcessSP(), m_address, and lldb_private::Expression::m_jit_process_wp.

Referenced by GetFixedText(), and lldb_private::ClangUserExpression::PrepareForParsing().

◆ isA()

bool lldb_private::UserExpression::isA ( const void *  ClassID) const
inlineoverridevirtual

Implements lldb_private::Expression.

Reimplemented in lldb_private::ClangUserExpression.

Definition at line 40 of file UserExpression.h.

References ID.

Referenced by lldb_private::LLVMUserExpression::isA().

◆ Language()

lldb::LanguageType lldb_private::UserExpression::Language ( ) const
inlineoverridevirtual

Return the language that should be used when parsing.

To use the default, return eLanguageTypeUnknown.

Reimplemented from lldb_private::Expression.

Definition at line 197 of file UserExpression.h.

References m_language.

◆ LockAndCheckContext()

bool UserExpression::LockAndCheckContext ( ExecutionContext exe_ctx,
lldb::TargetSP &  target_sp,
lldb::ProcessSP &  process_sp,
lldb::StackFrameSP &  frame_sp 
)
protected

◆ MatchesContext()

bool UserExpression::MatchesContext ( ExecutionContext exe_ctx)

Definition at line 96 of file UserExpression.cpp.

References LockAndCheckContext().

Referenced by Complete().

◆ NeedsValidation()

bool lldb_private::UserExpression::NeedsValidation ( )
inlineoverridevirtual

Return true if validation code should be inserted into the expression.

Implements lldb_private::Expression.

Definition at line 204 of file UserExpression.h.

◆ NeedsVariableResolution()

bool lldb_private::UserExpression::NeedsVariableResolution ( )
inlineoverridevirtual

Return true if external variables in the expression should be resolved.

Implements lldb_private::Expression.

Definition at line 207 of file UserExpression.h.

◆ Parse()

virtual bool lldb_private::UserExpression::Parse ( DiagnosticManager diagnostic_manager,
ExecutionContext exe_ctx,
lldb_private::ExecutionPolicy  execution_policy,
bool  keep_result_in_memory,
bool  generate_debug_info 
)
pure virtual

Parse the expression.

Parameters
[in]diagnostic_managerA diagnostic manager to report parse errors and warnings to.
[in]exe_ctxThe execution context to use when looking up entities that are needed for parsing (locations of functions, types of variables, persistent variables, etc.)
[in]execution_policyDetermines whether interpretation is possible or mandatory.
[in]keep_result_in_memoryTrue if the resulting persistent variable should reside in target memory, if applicable.
Returns
True on success (no errors); false otherwise.

Implemented in lldb_private::ClangUserExpression.

◆ Text()

const char* lldb_private::UserExpression::Text ( )
inlineoverridevirtual

Return the string that the parser should parse.

Implements lldb_private::Expression.

Definition at line 186 of file UserExpression.h.

References m_expr_text.

Member Data Documentation

◆ ID

char UserExpression::ID
staticprivate

LLVM RTTI support.

Definition at line 37 of file UserExpression.h.

Referenced by isA().

◆ kNoResult

const Status::ValueType lldb_private::UserExpression::kNoResult
static
Initial value:
=
0x1001

ValueObject::GetError() returns this if there is no result from the expression.

Definition at line 265 of file UserExpression.h.

Referenced by Evaluate(), lldb_private::CommandObjectExpression::EvaluateExpression(), and lldb_private::REPL::IOHandlerInputComplete().

◆ m_address

Address lldb_private::UserExpression::m_address
protected

The address the process is stopped in.

Definition at line 294 of file UserExpression.h.

Referenced by InstallContext(), and LockAndCheckContext().

◆ m_desired_type

ResultType lldb_private::UserExpression::m_desired_type
protected

The type to coerce the expression's result to.

If eResultTypeAny, inferred from the expression.

Definition at line 303 of file UserExpression.h.

Referenced by DesiredResultType().

◆ m_expr_prefix

std::string lldb_private::UserExpression::m_expr_prefix
protected

The text of the translation-level definitions, as provided by the user.

Definition at line 296 of file UserExpression.h.

Referenced by lldb_private::ClangUserExpression::CreateSourceCode().

◆ m_expr_text

std::string lldb_private::UserExpression::m_expr_text
protected

The text of the expression, as typed by the user.

Definition at line 295 of file UserExpression.h.

Referenced by lldb_private::ClangUserExpression::CreateSourceCode(), GetUserText(), lldb_private::ClangUserExpression::PrepareForParsing(), and Text().

◆ m_fixed_text

std::string lldb_private::UserExpression::m_fixed_text
protected

The text of the expression with fix-its applied.

  • this won't be set if the fixed text doesn't parse.

Definition at line 298 of file UserExpression.h.

Referenced by GetFixedText(), and lldb_private::ClangUserExpression::Parse().

◆ m_language

lldb::LanguageType lldb_private::UserExpression::m_language
protected

The language to use when parsing (eLanguageTypeUnknown means use defaults)

Definition at line 301 of file UserExpression.h.

Referenced by lldb_private::ClangUserExpression::ClangUserExpression(), Execute(), Language(), lldb_private::ClangUserExpression::Parse(), and lldb_private::ClangUserExpression::PrepareForParsing().

◆ m_options

EvaluateExpressionOptions lldb_private::UserExpression::m_options
protected

The documentation for this class was generated from the following files: