Struct Instance

pub struct Instance { /* private fields */ }

An instance used to execute a compiled program.

Implementations

impl Instance

pub fn warnings(&self) -> &[CompileError]

Returns the warnings generated during compilation.

pub fn run( &mut self, symbol: &str, timeframe: TimeFrame, ) -> impl Stream<Item = Result<Event, Error>> + '_

Runs the script against the full candlestick stream supplied by the injected DataProvider, starting from the beginning of available data.

This is equivalent to calling run_from with from_time = 0.

• CandlestickItem::Confirmed — advances bar_index.
• CandlestickItem::Realtime — same-timestamp ticks become RealtimeUpdate automatically; confirmed at stream end.
• CandlestickItem::HistoryEnd — skipped (internal boundary marker).

Returns immediately with Ok(()) if no DataProvider was passed to Instance::builder. Returns a stream of events produced by running the script against the candlestick stream from the injected DataProvider.

Equivalent to run_from with from_time = 0.

pub fn run_from( &mut self, symbol: &str, timeframe: TimeFrame, from_time: i64, ) -> impl Stream<Item = Result<Event, Error>> + '_

Returns a stream of events produced by running the script, starting at from_time.

Each bar’s execution yields Event::BarStart, any log/alert/draw events, then Event::BarEnd. The stream yields Event::HistoryEnd when the boundary marker is received.

pub async fn run_to_end( &mut self, symbol: &str, timeframe: TimeFrame, ) -> Result<(), Error>

Runs the script to completion, discarding all events.

This is a convenience wrapper around run for callers that only need the final chart state.

pub async fn run_from_to_end( &mut self, symbol: &str, timeframe: TimeFrame, from_time: i64, ) -> Result<(), Error>

Runs the script to completion starting at from_time, discarding all events.

pub fn chart(&self) -> &Chart

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);
    }
}

pub fn script_info(&self) -> &ScriptInfo

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

pub fn candlesticks(&self) -> &Series<Candlestick>

Returns a reference to the candlestick series accumulated during execution.

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

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

pub fn into_chart(self) -> Chart

Consumes the instance and returns the chart data.

This avoids cloning the chart when the instance is no longer needed (e.g. in a WASM playground that only needs the chart for rendering).

impl Instance

pub fn builder<'a, P>( provider: P, source: &'a str, timeframe: TimeFrame, symbol: impl Into<String>, ) -> InstanceBuilder<'a, ()>

where P: DataProvider + 'static,

Creates a new InstanceBuilder for the given provider, source, timeframe and symbol string.

provider supplies the main chart K-lines consumed by Instance::run() and the data for any request.security() calls. For simple single-symbol backtests pass a Vec<Candlestick> directly; for multi-symbol or live data implement DataProvider directly.

Examples

use openpine_vm::{Candlestick, Instance, TimeFrame, TradeSession};

let source = r#"
    //@version=6
    indicator("My Script")
    plot(close)
"#;
let bar = Candlestick::new(
    1_700_000_000_000,
    150.0,
    155.0,
    149.0,
    153.0,
    1_000_000.0,
    0.0,
    TradeSession::Regular,
);
let provider = vec![bar];
let mut instance = Instance::builder(provider, source, TimeFrame::days(1), "NASDAQ:AAPL")
    .with_path("my_script.pine")
    .build()
    .await?;

instance
    .run_to_end("NASDAQ:AAPL", TimeFrame::days(1))
    .await?;

let chart = instance.chart();
for (id, graph) in chart.series_graphs() {
    println!("Graph {:?}: {:?}", id, graph);
}

pub fn builder_from_project<'a, P>( provider: P, project: &'a Project, timeframe: TimeFrame, symbol: impl Into<String>, ) -> InstanceBuilder<'a, ()>

where P: DataProvider + 'static,

Creates a new InstanceBuilder from an already-loaded [Project].

Skips the parse + load phase, going straight to optimize + compile when InstanceBuilder::build() is called. This is useful when the caller has already loaded the project (e.g. to share a cached LoadResult between compilation and LSP analysis).

impl Instance

pub fn restore_state(data: &[u8]) -> Result<RestoreBuilder, SnapshotError>

Deserializes a snapshot and returns a RestoreBuilder for configuring optional parameters before completing the restore.

Errors

Returns SnapshotError::Decode if decoding fails, or SnapshotError::VersionMismatch if the snapshot version does not match the current build.

impl Instance

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.

Errors

Returns SnapshotError::Encode if bincode serialization fails.