Struct RunHandle 

pub struct RunHandle { /* private fields */ }

A handle to an active execution run returned by Instance::run.

Call next_event to iterate events one at a time. The handle implements Deref and DerefMut targeting Instance, so all instance methods — including save_state — are available directly through the handle while the run is in progress.

Example

let mut handle = instance.run("NASDAQ:AAPL", TimeFrame::days(1));
while let Some(result) = handle.next_event().await {
    let event = result?;
    if matches!(event, Event::BarEnd) && handle.current_bar_confirmed() {
        let snapshot = handle.save_state()?;
        persist_snapshot(snapshot);
    }
}
let instance = handle.into_instance();

Implementations

impl RunHandle

pub fn into_instance(self) -> Instance

Consumes the handle and returns the instance.

pub async fn next_event(&mut self) -> Option<Result<Event, Error>>

Returns the next event from the run, or None when execution is complete.

Methods from Deref<Target = Instance>

pub fn program(&self) -> &Program

Returns the compiled program held by this instance.

The Program is reference-counted (Arc internally) so cloning it is cheap. Used by providers to cache compiled programs across stream restarts.

pub fn reset(&mut self)

Resets the instance to its post-build state, as if no bars had been executed.

All runtime state — variable series, chart visuals, events, strategy positions, security sub-states, and bar counters — is discarded and re-initialised from scratch. The compiled program, symbol/timeframe configuration, data provider, execution limits, and output mode are preserved unchanged.

Note: Input values that were overridden via InstanceBuilder::with_input_value are not preserved across a reset; inputs revert to their script-default values.

Examples

let mut instance = instance
    .run_to_end("NASDAQ:AAPL", TimeFrame::days(1))
    .await?;
instance.reset();
// instance is now clean and ready to re-run

pub fn warnings(&self) -> Warnings

Returns the warnings generated during compilation, bundled with source files so the caller can render them via Warnings::display().

pub fn gc_collect_all(&mut self)

Runs a full garbage collection cycle on the GC arena.

Normally the VM collects incrementally during execution. Call this after a batch of bars to reclaim all unreachable GC objects at once.

pub fn symbol_info(&self) -> &SymbolInfo

Returns a reference to the chart containing the visuals.

The [Chart] holds all plots, lines, labels, boxes, and other visuals produced by the script. Query it after calling execute().

Examples

let chart = instance.chart();

// Iterate over per-bar series graphs (plot, bgcolor, fill, etc.)
for (id, series_graph) in chart.series_graphs() {
    if let Some(plot) = series_graph.as_plot() {
        println!("Plot '{:?}': {} bars", plot.title, plot.series.len());
    }
}

// Iterate over non-series graphs (label, line, box, table, etc.)
for (id, graph) in chart.graphs() {
    if let Some(label) = graph.as_label() {
        println!("Label at ({}, {}): {:?}", label.x, label.y, label.text);
    }
}

Returns the symbol info for the current chart symbol.

pub fn chart(&self) -> &Chart

Returns the chart state produced by this instance.

pub fn script_info(&self) -> &ScriptInfo

Returns a reference to the script info (script type, inputs, etc.).

pub fn total_bars(&self) -> usize

Returns the total number of bars processed since execution started, including bars that have been truncated from memory.

pub fn current_bar_confirmed(&self) -> bool

Returns whether the current bar has been confirmed.

Historical bars are always confirmed immediately after execution. Realtime bars become confirmed only after RealtimeConfirmed runs, either explicitly at stream end or automatically when a later realtime timestamp arrives.

pub fn strategy_report(&self) -> Option<StrategyReport>

Returns the strategy backtest report, or None if the script is not a strategy.

pub fn save_state(&mut self) -> Result<Vec<u8>, SnapshotError>

Serializes the current VM state to a binary blob.

The returned bytes encode the full program, all variables, inputs, GC-heap objects, chart, strategy state, and configuration. Pass them to Instance::restore_state to resume execution.

The current realtime bar must be confirmed before calling this method (e.g. by executing ExecuteMode::Confirm). Returns SnapshotError::UnconfirmedBar otherwise.

Candlestick data is not included in the snapshot. When run() is called on a restored instance, the VM automatically passes last_bar_time + 1 to the data provider.

Errors

Returns SnapshotError::UnconfirmedBar if the current bar has not been confirmed, or SnapshotError::Encode if postcard serialization fails.

Trait Implementations

impl Deref for RunHandle

type Target = Instance

The resulting type after dereferencing.

fn deref(&self) -> &Instance

Dereferences the value.

impl DerefMut for RunHandle

fn deref_mut(&mut self) -> &mut Instance

Mutably dereferences the value.