Struct Session 

pub struct Session<'a> { /* private fields */ }

One backend, ready to be invoked as many times as an embedder likes.

Implementations

impl Session<'_>

pub fn build_time(&self) -> Duration

What building this session’s backend cost.

pub fn invoke( &mut self, module: &str, entry: &str, args: Vec<Value>, ) -> Result<Value, RuntimeError>

Calls module.entry with the values args, and answers what it produced.

The seam an application uses. invoke holds args to the signature the checker resolved for module.entry — the parameter count, and each value against its declared type, followed into a declared struct’s fields — and refuses before the first instruction if they do not match. Both backends answer it the same way; nothing here knows which one is underneath.

pub fn run( &mut self, module: &str, entry: &str, args: &[&str], ) -> Result<Value, RuntimeError>

Runs module.entry as a command would, handing it args as the process arguments an entry may declare.

The other seam, and the only one there used to be. It is what Session::decide uses to reach rules.embedded.decideRequest, which is the control the Host API boundary is measured with.

pub fn evaluate( &mut self, module: &str, entry: &str, pr: &PullRequest, ) -> Result<Decision, String>

Decides pr by invoking module.entry with it, and reads the Decision back.

This is what an application calls once per request. Nothing crosses the Host API boundary: the pull request goes in as an argument and the decision comes back as a result, so a run of it makes no host call at all and needs no capability.

pub fn evaluate_within( &mut self, limits: Limits, module: &str, entry: &str, pr: &PullRequest, ) -> Result<Decision, String>

Decides pr the same way, bounded by limits for this request and no other.

This is what an application that runs somebody else’s rules calls. A rule package is not the application’s code: it can loop, and an application would rather be told which request went wrong than stop serving. invoke_within installs a Budget built from limits as the invocation is entered, so the fuel, the deadline and the host-call limit are this request’s – and the next request gets its own, on the same Vm, with none of the 168 allocations that rebuilding a backend per request costs.

The deadline runs from here rather than from wherever the Limits were written, which is what makes a per-request deadline mean the request.

A failure comes back as the message it came back as; nothing about a stopped invocation damages the session, exactly as for a host that failed.

pub fn decide( &mut self, module: &str, entry: &str, request: &str, ) -> Result<Decision, String>

The same decision the other way: module.entry is run with the request identifier as its one process argument, fetches the pull request through reviews.pull, and reports the answer through reviews.record.

pub fn decide_within( &mut self, limits: Limits, module: &str, entry: &str, request: &str, ) -> Result<Decision, String>

The boundary route, bounded by limits for this request and no other.

The counterpart of Session::evaluate_within for the way in that makes host calls, and the reason it is here as well as that one: ADR 0024 says max_host_calls is the control that bounds effects exactly, where fuel bounds work only to within a straight line. An application that wants to cap what one request may do to the outside world sets it, and until issue #152 it could only set it for the life of the session.

pub fn instructions(&self) -> Option<u64>

How many instructions every invocation on this session has executed between them, or None on the interpreter, which counts none.