slang::ast::EvalContext class

A container for all context required to evaluate a statement or expression.

Mostly this involves tracking the callstack and maintaining storage for local variables.

Public types

struct Frame
Represents a single frame in the call stack.
struct ActiveIterator
The current position of an array method iterator that is active during evaluation, which is needed if the iterator's index method is called.

Constructors, destructors, conversion operators

EvalContext(const ASTContext& astCtx, bitmask<EvalFlags> flags = {}) explicit
Constructs a new EvalContext instance.
EvalContext(const Symbol& symbol, bitmask<EvalFlags> flags = {}) explicit
Constructs a new EvalContext instance.

Public functions

Compilation& getCompilation() const
Gets the compilation associated with the context.
void reset()
Resets the evaluation context back to an initial constructed state.
ConstantValue* createLocal(const ValueSymbol* symbol, ConstantValue value = nullptr)
Creates storage for a local variable in the current frame.
ConstantValue* findLocal(const ValueSymbol* symbol)
Gets the current value for the given local variable symbol.
void deleteLocal(const ValueSymbol* symbol)
Removes a previously created local.
void pushIterator(ActiveIterator& iterator)
Marks the given iterator as active.
void popIterator()
Removes the most recently pushed active iterator.
const ActiveIterator* findIterator(const ValueSymbol& symbol) const
Finds the active iterator for the given iterator variable, or returns nullptr if it is not active.
bool pushFrame(const SubroutineSymbol& subroutine, SourceLocation callLocation, LookupLocation lookupLocation)
Push a new frame onto the call stack.
void pushEmptyFrame()
Pushes an empty frame onto the call stack.
void popFrame()
Pop the active frame from the call stack.
void pushLValue(LValue& lval)
Pushes an lvalue onto the stack for later reference during evaluation.
void popLValue()
Pops the top of the lvalue stack (requires that the stack be non-empty).
LValue* getTopLValue() const
Gets the top of the lvalue stack, or nullptr if the stack is empty.
bool step(SourceLocation loc)
Records the fact that we are executing another statement.
uint32_t getSteps() const
Gets the number of steps (statements) executed so far.
bool tryAddSteps(uint32_t count)
Records count steps that were executed on behalf of this context elsewhere, such as by a memoized function call.
bool checkBitCount(uint64_t bits, SourceRange range)
Checks whether a computed bit count exceeds the configured constant value size limit.
bool checkMaxValue(const ConstantValue& val, SourceRange range)
Checks whether the given constant value exceeds the configured maximum size limit.
bool inFunction() const
Returns true if the context is currently within a function call, and false if this is a top-level expression.
bool cacheResults() const
Indicates whether the results of evaluating expressions using this context can be cached in each expression's constant pointer.
auto disableCaching()
If result caching is enabled, this method disables it and returns an object that when destructed will restore the previous caching mode.
const Frame& topFrame() const
Gets the top of the call stack.
const Symbol* getDisableTarget() const
If a disable statement has been evaluated, this returns a pointer to the block that should be disabled (presumed to be higher up in the stack).
SourceRange getDisableRange() const
If a disable statement has been evaluated, this returns the source range denoting where that statement occurred.
void setDisableTarget(const Symbol* symbol, SourceRange range)
Sets the target block that should be disabled, based on evaluating a disable statement.
void setQueueTarget(const ConstantValue* cv)
Sets the target queue value for use with unbounded '$' expressions.
const ConstantValue* getQueueTarget() const
Gets the target queue value for use with unbounded '$' expressions.
size_t getCallDepth() const
Gets the number of frames on the call stack.
void preventMemoization()
Records that the evaluation depends on something other than the functions being called and the values of their arguments, such as the evaluation flags or the location of a call site, so the result of the outermost function call can't be memoized.
bool takeMemoizationPrevented()
Returns whether preventMemoization has been called and clears the flag.
size_t getDiagCount() const
Gets the number of diagnostics currently recorded by this context.
std::string dumpStack() const
Dumps the contents of the call stack to a string for debugging.
Diagnostics getAllDiagnostics() const
Gets the set of diagnostics that have been produced during constant evaluation.
Diagnostic& addDiag(DiagCode code, SourceLocation location)
Records a diagnostic under the current evaluation context.
Diagnostic& addDiag(DiagCode code, SourceRange range)
Records a diagnostic under the current evaluation context.
void reportAllDiags()
Issues all recorded diagnostics to the associated AST context.
void reportWarnings()
Issues only warnings to the associated AST context.
void reportStack(Diagnostic& diag) const
Reports the current function call stack as notes to the given diagnostic.

Public variables

ASTContext astCtx
The AST context in which the evaluation is occurring.
bitmask<EvalFlags> flags
Flags that control evaluation.

Function documentation

ConstantValue* slang::ast::EvalContext::findLocal(const ValueSymbol* symbol)

Gets the current value for the given local variable symbol.

Returns nullptr if the symbol cannot be found.

void slang::ast::EvalContext::deleteLocal(const ValueSymbol* symbol)

Removes a previously created local.

Pointers to the local's storage will be invalidated.

void slang::ast::EvalContext::pushIterator(ActiveIterator& iterator)

Marks the given iterator as active.

It must remain alive until a corresponding call to popIterator.

void slang::ast::EvalContext::pushEmptyFrame()

Pushes an empty frame onto the call stack.

Intended for use with on-the-fly evaluation in a scripting context.

void slang::ast::EvalContext::pushLValue(LValue& lval)

Pushes an lvalue onto the stack for later reference during evaluation.

NOTE: the lvalue storage must remain alive for as long as it remains on the eval context's lvalue stack.

bool slang::ast::EvalContext::step(SourceLocation loc)

Records the fact that we are executing another statement.

This is used to count the number of statements executed so far to detect if we've been evaluating a single constant function for too long.

bool slang::ast::EvalContext::tryAddSteps(uint32_t count)

Records count steps that were executed on behalf of this context elsewhere, such as by a memoized function call.

If doing so would reach the step limit, nothing is recorded and false is returned.

bool slang::ast::EvalContext::checkBitCount(uint64_t bits, SourceRange range)

Checks whether a computed bit count exceeds the configured constant value size limit.

If the limit is exceeded, a diagnostic is issued and false is returned. Use this before allocating a large value to prevent out-of-memory crashes.

bool slang::ast::EvalContext::checkMaxValue(const ConstantValue& val, SourceRange range)

Checks whether the given constant value exceeds the configured maximum size limit.

If the limit is exceeded, a diagnostic is issued and false is returned.

auto slang::ast::EvalContext::disableCaching()

If result caching is enabled, this method disables it and returns an object that when destructed will restore the previous caching mode.

Otherwise does nothing.

const Symbol* slang::ast::EvalContext::getDisableTarget() const

If a disable statement has been evaluated, this returns a pointer to the block that should be disabled (presumed to be higher up in the stack).

Otherwise returns nullptr.

SourceRange slang::ast::EvalContext::getDisableRange() const

If a disable statement has been evaluated, this returns the source range denoting where that statement occurred.

Otherwise returns an empty range.

void slang::ast::EvalContext::setDisableTarget(const Symbol* symbol, SourceRange range)

Sets the target block that should be disabled, based on evaluating a disable statement.

This can be set to nullptr to clear out the target once it has been found the disable is completed.

void slang::ast::EvalContext::setQueueTarget(const ConstantValue* cv)

Sets the target queue value for use with unbounded '$' expressions.

If set to nullptr, the target is cleared.

const ConstantValue* slang::ast::EvalContext::getQueueTarget() const

Gets the target queue value for use with unbounded '$' expressions.

Returns nullptr if there is no queue target active.