Struct starlark::eval::Evaluator

pub struct Evaluator<'v, 'a> {
    pub extra: Option<&'a dyn AnyLifetime<'a>>,
    /* private fields */
}

Holds everything about an ongoing evaluation (local variables, globals, module resolution etc).

Fields

extra: Option<&'a dyn AnyLifetime<'a>>

Field that can be used for any purpose you want (can store types you define). Typically accessed via native functions you also define.

Implementations

impl<'v, 'a> Evaluator<'v, 'a>

pub fn eval_statements(&mut self, statements: AstModule) -> Result<Value<'v>>

Evaluate statements in the existing context. This function is designed for debugging, not production use.

There are lots of health warnings on this code. Might not work with frozen modules, unassigned variables, nested definitions etc. It would be a bad idea to rely on the results of continued execution after evaluating stuff randomly.

impl<'v, 'a> Evaluator<'v, 'a>

pub fn local_variables(&self) -> SmallMap<String, Value<'v>>

Obtain the local variables currently in scope. When at top-level these will be Module variables, otherwise local definitions. The precise number of variables may change over time due to optimisation. The only legitimate use of this function is for debugging.

impl<'v, 'a> Evaluator<'v, 'a>

pub fn new(module: &'v Module) -> Self

Crate a new Evaluator specifying the Module used for module variables.

If your program contains load() statements, you also need to call set_loader.

pub fn disable_gc(&mut self)

Disables garbage collection from now onwards. Cannot be re-enabled. Usually called because you have captured Value’s unsafely, either in global variables or the extra field.

pub fn verbose_gc(&mut self)

Enable GC logging.

pub fn enable_static_typechecking(&mut self, enable: bool)

Enable static typechecking. For example:

def foo() -> int: return "hello"

would fail when static typechecking is enabled even if foo is never called.

pub fn set_loader(&mut self, loader: &'a dyn FileLoader)

Set the FileLoader used to resolve load() statements. A list of all load statements can be obtained through AstModule::loads.

pub fn enable_profile(&mut self, mode: &ProfileMode) -> Result<()>

Enable profiling, allowing Evaluator::write_profile to be used. Profilers add overhead, and while some profilers can be used together, it’s better to run at most one profiler at a time.

pub fn write_profile<P: AsRef<Path>>(&mut self, filename: P) -> Result<()>

Write a profile to a file. Only valid if corresponding profiler was enabled.

pub fn gen_profile(&mut self) -> Result<ProfileData>

Generate profile for a given mode. Only valid if corresponding profiler was enabled.

pub fn coverage(&self) -> Result<HashSet<ResolvedFileSpan>>

Get code coverage.

Works if statement profile is enabled.

Note coverage is not precise, because

• some optimizer transformations may create incorrect spans
• some optimizer transformations may remove statements

pub fn enable_terminal_breakpoint_console(&mut self)

Enable interactive breakpoint(). When enabled, breakpoint() reads commands from stdin and write to stdout. When disabled (default), breakpoint() function results in error.

pub fn call_stack(&self) -> CallStack

Obtain the current call-stack, suitable for use in diagnostics.

pub fn call_stack_top_frame(&self) -> Option<Frame>

Obtain the top frame on the call-stack. May be None if the call happened via native functions.

pub fn call_stack_count(&self) -> usize

Current size (in frames) of the stack.

pub fn call_stack_top_location(&self) -> Option<FileSpan>

Obtain the top location on the call-stack. May be None if the call happened via native functions.

pub fn set_print_handler(&mut self, handler: &'a (dyn PrintHandler + 'a))

Set the handler invoked when print function is used.

pub fn heap(&self) -> &'v Heap

The active heap where Values are allocated.

pub fn module(&self) -> &'v Module

Module which was passed to the evaluator.

pub fn frozen_heap(&self) -> &'v FrozenHeap

The frozen heap. It’s possible to allocate FrozenValues here, but often not a great idea, as they will remain allocated as long as the results of this execution are required. Suitable for use with add_reference and OwnedFrozenValue::owned_frozen_value.

pub fn set_module_variable_at_some_point( &mut self, name: &str, value: Value<'v> ) -> Result<()>

Set a variable in the top-level module currently being processed. This may not be the module the function is being called in.

Any variables which are set will be available in the Module after evaluation returns. If those variables are also existing top-level variables, then the program from that point on will incorporate those values. If they aren’t existing top-level variables, they will be ignored. These details are subject to change. As such, use this API with a healthy dose of caution and in limited settings.

pub unsafe fn garbage_collect(&mut self)

Perform a garbage collection. After this operation all Values not reachable from the evaluator will be invalid, and using them will lead to a segfault. Do not call during Starlark evaluation.

pub fn set_max_callstack_size(&mut self, stack_size: usize) -> Result<()>

Sets max call stack size. Stack allocation will happen on entry point of evaluation if not allocated yet.

impl<'v, 'a> Evaluator<'v, 'a>

pub fn eval_module( &mut self, ast: AstModule, globals: &Globals ) -> Result<Value<'v>>

Evaluate an AstModule with this Evaluator, modifying the in-scope Module as appropriate.

pub fn eval_function( &mut self, function: Value<'v>, positional: &[Value<'v>], named: &[(&str, Value<'v>)] ) -> Result<Value<'v>>

Evaluate a function stored in a Value, passing in positional and named arguments.

Trait Implementations

impl Drop for Evaluator<'_, '_>

fn drop(&mut self)

Executes the destructor for this type.