Skip to main content

Run Class

Live pipeline handle: push inputs in, pull outputs out. More...

Declaration

class simaai::neat::Run { ... }

Included Headers

#include <Run.h>

Friends Index

classMeasureScope
classGraph

Public Constructors Index

Run ()=default

Construct an empty Run; assign from Graph::build() before use. More...

Run (const Run &)=delete

Non-copyable. More...

Run (Run &&) noexcept

Move-constructible. More...

Private Constructors Index

Run (std::shared_ptr< runtime::RunCore > core)

Public Destructor Index

~Run ()

Cleanly tears down the pipeline. More...

Public Operators Index

Run &operator= (const Run &)=delete

Non-copyable. More...

Run &operator= (Run &&) noexcept

Move-assignable. More...

operator bool () const noexcept

Returns true if the Run is alive (constructed by Graph::build, not yet stopped). More...

Public Member Functions Index

boolcan_push () const

Returns true if the input side accepts pushes (not closed). More...

boolcan_pull () const

Returns true if the output side may produce more samples (pipeline not at EOS). More...

boolrunning () const

Returns true if the pipeline is in PLAYING state. More...

std::vector< std::string >input_names () const

Names accepted by push(name, ...) for graph-backed Runs. Empty for unnamed/linear Runs. More...

std::vector< std::string >output_names () const

Names accepted by pull(name, ...) for graph-backed Runs. Empty for unnamed/linear Runs. More...

boolpush (const std::vector< cv::Mat > &inputs)

Push cv::Mat inputs into the pipeline. More...

boolpush (std::string_view input_name, const std::vector< cv::Mat > &inputs)

Push cv::Mat inputs into a named graph ingress. Use for multi-input graphs. More...

booltry_push (const std::vector< cv::Mat > &inputs)

Non-blocking variant of push; returns false immediately if the queue is full. More...

booltry_push (std::string_view input_name, const std::vector< cv::Mat > &inputs)

Non-blocking named-ingress variant. More...

boolpush (const TensorList &inputs)

Push Tensor inputs (one per ingress port). More...

boolpush (std::string_view input_name, const TensorList &inputs)

Push Tensor inputs into a named graph ingress. Use for multi-input graphs. More...

booltry_push (const TensorList &inputs)

Non-blocking variant. More...

booltry_push (std::string_view input_name, const TensorList &inputs)

Non-blocking named-ingress variant. More...

boolpush (const Sample &msgs)

Push full Sample inputs (carrying per-buffer metadata). More...

boolpush (std::string_view input_name, const Sample &msgs)

Push full Sample inputs into a named graph ingress. Use for multi-input graphs. More...

booltry_push (const Sample &msgs)

Non-blocking variant. More...

booltry_push (std::string_view input_name, const Sample &msgs)

Non-blocking named-ingress variant. More...

boolpush_holder (const std::shared_ptr< void > &holder)

Internal: pushes a GstBuffer held by a tensor ref to preserve plugin metadata. More...

booltry_push_holder (const std::shared_ptr< void > &holder)

Non-blocking variant of push_holder. More...

voidclose_input ()

Send EOS into the pipeline. More...

PullStatuspull (int timeout_ms, Sample &out, PullError *err=nullptr)

Pull the next output sample with a structured status return. More...

PullStatuspull (std::string_view output_name, int timeout_ms, Sample &out, PullError *err=nullptr)

Pull from a named graph output with structured status. More...

std::optional< Sample >pull (int timeout_ms=-1)

Convenience pull returning an optional Sample (empty on timeout/closed; throws on error). More...

std::optional< Sample >pull (std::string_view output_name, int timeout_ms=-1)

Convenience named-output pull (empty on timeout/closed; throws on error). More...

TensorListpull_tensors (int timeout_ms=-1)

Pull and unpack the next sample as a TensorList. More...

TensorListpull_tensors (std::string_view output_name, int timeout_ms=-1)

Pull and unpack from a named graph output as a TensorList. More...

Samplepull_samples (int timeout_ms=-1)

Pull the next sample as a Sample (preserves per-sample metadata). More...

Samplepull_samples (std::string_view output_name, int timeout_ms=-1)

Pull samples from a named graph output (preserves per-sample metadata). More...

TensorListrun (const std::vector< cv::Mat > &inputs, int timeout_ms=-1)

One-shot synchronous push+pull from cv::Mat inputs. More...

TensorListrun (const TensorList &inputs, int timeout_ms=-1)

One-shot synchronous push+pull from Tensor inputs. More...

Samplerun (const Sample &inputs, int timeout_ms=-1)

One-shot synchronous push+pull from Sample inputs. More...

MeasureScopestart_measurement (const MeasureOptions &opt={})

Start observing a caller-owned push/pull interval without consuming outputs. More...

intwarmup (const std::vector< cv::Mat > &inputs, int warm=-1, int timeout_ms=-1)

Run warm warm-up inferences before measurement begins. More...

RunStatsstats () const

Returns end-to-end push/pull/latency stats. More...

InputStreamStatsinput_stats () const

Returns input-side telemetry (push counts, drops, timing). More...

RunDiagSnapshotdiag_snapshot () const

Returns the full diagnostic snapshot (per-stage, per-element, per-pad). More...

PowerSummarypower_summary () const

Returns the optional SOM power telemetry summary for this Run. More...

RunMeasurementSummarymeasurement_summary () const

Returns latency, throughput, input stats, and optional power telemetry in one call. More...

RuntimeMetricsmetrics (const RuntimeMetricsOptions &opt={}) const

Returns the preferred unified runtime metrics surface. More...

std::stringmetrics_report (const RuntimeMetricsOptions &opt={}, RuntimeMetricsFormat format=RuntimeMetricsFormat::Text) const

Render unified runtime metrics in the requested format. More...

std::stringmetrics_report (RuntimeMetricsFormat format) const

Convenience overload for selecting the output format with default options. More...

std::stringreport (const RunReportOptions &opt={}) const

Returns a human-readable formatted report combining stats and diagnostics. More...

std::stringlast_error () const

Returns the most recent runtime error string (empty if no error occurred). More...

std::stringdiagnostics_summary () const

Returns a short diagnostics summary suitable for logging or error reports. More...

voidstop ()

Stop the pipeline immediately (transitions to NULL). After stop, the Run is no longer running. More...

voidclose ()

Alias for stop(). Releases resources. More...

Private Member Functions Index

voidrequire_async_mode (const char *where) const
voidrequire_async_pull_mode (const char *where) const
voidenqueue_run_images (const std::vector< cv::Mat > &inputs)
voidenqueue_run_tensors (const TensorList &inputs)
voidenqueue_run_samples (const Sample &inputs)
TensorListpull_tensors_strict (int timeout_ms)
Samplepull_samples_strict (int timeout_ms)
boolpush_impl (const cv::Mat &input, bool block)
boolpush_impl (const simaai::neat::Tensor &input, bool block)
boolpush_holder_impl (const std::shared_ptr< void > &holder, bool block)
boolpush_message_impl (const Sample &msg, bool block)
boolpush_sample_impl (const Sample &msg, bool block)

Private Member Attributes Index

std::shared_ptr< runtime::RunCore >core_

Private Static Functions Index

static Runcreate (InputStream stream, const RunOptions &opt, const struct InputStreamOptions &stream_opt, RunMode mode=RunMode::Async, const std::optional< InputOptions > &tensor_input_opt_for_cv=std::nullopt, pipeline_internal::InputRouteProcessorPtr input_route_processor=nullptr)

Description

Live pipeline handle: push inputs in, pull outputs out.

A Run is what Graph::build() returns. It owns the live GStreamer pipeline plus its internal worker threads (typically 5–15 per Run, including streaming threads, dispatcher pool threads, and a bus watcher). Application code drives the Run by push()-ing inputs and pull()-ing outputs (or run() for one-shot synchronous use).

 auto run = graph.build(TensorList{input});
 run.push(TensorList{another_input});
 auto sample = run.pull(/ * timeout_ms = * / 100);

Thread safety: push() from one thread and pull() from another is safe. Multiple threads push-ing the same Run concurrently is NOT safe — serialize push from one thread or use external synchronization.

Runs are non-copyable but movable. Destroying a Run shuts down its pipeline cleanly (sends EOS, drains, transitions to NULL).

See Also

Graph::build for how a Run is constructed

See Also

RunOptions for runtime configuration

See Also

"Runs and the parallelism story" (§0.13 of the design deep dive)

Definition at line 562 of file Run.h.

Friends

Graph

friend class Graph

Definition at line 719 of file Run.h.

719 friend class Graph;

MeasureScope

friend class MeasureScope

Definition at line 695 of file Run.h.

695 friend class MeasureScope;

Public Constructors

Run()

simaai::neat::Run::Run ()
default

Construct an empty Run; assign from Graph::build() before use.

Definition at line 565 of file Run.h.

Run()

simaai::neat::Run::Run (const Run &)
delete

Non-copyable.

Definition at line 566 of file Run.h.

Run()

simaai::neat::Run::Run (Run &&)
noexcept

Move-constructible.

Definition at line 569 of file Run.h.

Private Constructors

Run()

simaai::neat::Run::Run (std::shared_ptr< runtime::RunCore > core)
explicit

Definition at line 702 of file Run.h.

Public Destructor

~Run()

simaai::neat::Run::~Run ()

Cleanly tears down the pipeline.

Definition at line 571 of file Run.h.

Public Operators

operator bool()

simaai::neat::Run::operator bool ()
explicit noexcept

Returns true if the Run is alive (constructed by Graph::build, not yet stopped).

Definition at line 574 of file Run.h.

operator=()

Run & simaai::neat::Run::operator= (const Run &)
delete

Non-copyable.

Definition at line 567 of file Run.h.

operator=()

Run & simaai::neat::Run::operator= (Run &&)
noexcept

Move-assignable.

Definition at line 570 of file Run.h.

Public Member Functions

can_pull()

bool simaai::neat::Run::can_pull ()

Returns true if the output side may produce more samples (pipeline not at EOS).

Definition at line 578 of file Run.h.

can_push()

bool simaai::neat::Run::can_push ()

Returns true if the input side accepts pushes (not closed).

Definition at line 576 of file Run.h.

close()

void simaai::neat::Run::close ()

Alias for stop(). Releases resources.

Definition at line 692 of file Run.h.

close_input()

void simaai::neat::Run::close_input ()

Send EOS into the pipeline.

Drain remaining outputs by continuing to pull until PullStatus::Closed.

Definition at line 619 of file Run.h.

diag_snapshot()

RunDiagSnapshot simaai::neat::Run::diag_snapshot ()

Returns the full diagnostic snapshot (per-stage, per-element, per-pad).

Definition at line 670 of file Run.h.

diagnostics_summary()

std::string simaai::neat::Run::diagnostics_summary ()

Returns a short diagnostics summary suitable for logging or error reports.

Definition at line 687 of file Run.h.

input_names()

std::vector< std::string > simaai::neat::Run::input_names ()

Names accepted by push(name, ...) for graph-backed Runs. Empty for unnamed/linear Runs.

Definition at line 582 of file Run.h.

input_stats()

InputStreamStats simaai::neat::Run::input_stats ()

Returns input-side telemetry (push counts, drops, timing).

Definition at line 668 of file Run.h.

last_error()

std::string simaai::neat::Run::last_error ()

Returns the most recent runtime error string (empty if no error occurred).

Definition at line 685 of file Run.h.

measurement_summary()

RunMeasurementSummary simaai::neat::Run::measurement_summary ()

Returns latency, throughput, input stats, and optional power telemetry in one call.

Definition at line 674 of file Run.h.

metrics()

RuntimeMetrics simaai::neat::Run::metrics (const RuntimeMetricsOptions & opt={})

Returns the preferred unified runtime metrics surface.

Definition at line 676 of file Run.h.

metrics_report()

std::string simaai::neat::Run::metrics_report (const RuntimeMetricsOptions & opt={}, RuntimeMetricsFormat format=RuntimeMetricsFormat::Text)

Render unified runtime metrics in the requested format.

Definition at line 678 of file Run.h.

metrics_report()

std::string simaai::neat::Run::metrics_report (RuntimeMetricsFormat format)

Convenience overload for selecting the output format with default options.

Definition at line 681 of file Run.h.

output_names()

std::vector< std::string > simaai::neat::Run::output_names ()

Names accepted by pull(name, ...) for graph-backed Runs. Empty for unnamed/linear Runs.

Definition at line 584 of file Run.h.

power_summary()

PowerSummary simaai::neat::Run::power_summary ()

Returns the optional SOM power telemetry summary for this Run.

Definition at line 672 of file Run.h.

pull()

PullStatus simaai::neat::Run::pull (int timeout_ms, Sample & out, PullError * err=nullptr)

Pull the next output sample with a structured status return.

Parameters
timeout_ms

Wait up to this many ms; -1 waits forever; 0 is non-blocking.

out

Filled with the next sample on Ok.

err

Optional out-parameter populated on Error with a structured PullError.

Returns

Ok, Timeout, Closed, or Error.

Definition at line 627 of file Run.h.

pull()

PullStatus simaai::neat::Run::pull (std::string_view output_name, int timeout_ms, Sample & out, PullError * err=nullptr)

Pull from a named graph output with structured status.

Use this when a graph has multiple terminal outputs. pull() without a name remains the default-output convenience API for the common single-output case.

Definition at line 634 of file Run.h.

pull()

std::optional< Sample > simaai::neat::Run::pull (int timeout_ms=-1)

Convenience pull returning an optional Sample (empty on timeout/closed; throws on error).

Definition at line 637 of file Run.h.

pull()

std::optional< Sample > simaai::neat::Run::pull (std::string_view output_name, int timeout_ms=-1)

Convenience named-output pull (empty on timeout/closed; throws on error).

Definition at line 639 of file Run.h.

pull_samples()

Sample simaai::neat::Run::pull_samples (int timeout_ms=-1)

Pull the next sample as a Sample (preserves per-sample metadata).

Definition at line 645 of file Run.h.

pull_samples()

Sample simaai::neat::Run::pull_samples (std::string_view output_name, int timeout_ms=-1)

Pull samples from a named graph output (preserves per-sample metadata).

Definition at line 647 of file Run.h.

pull_tensors()

TensorList simaai::neat::Run::pull_tensors (int timeout_ms=-1)

Pull and unpack the next sample as a TensorList.

Definition at line 641 of file Run.h.

pull_tensors()

TensorList simaai::neat::Run::pull_tensors (std::string_view output_name, int timeout_ms=-1)

Pull and unpack from a named graph output as a TensorList.

Definition at line 643 of file Run.h.

push()

bool simaai::neat::Run::push (const std::vector< cv::Mat > & inputs)

Push cv::Mat inputs into the pipeline.

Multi-input models accept one Mat per ingress.

Returns

true on success; behavior on full queue is governed by RunOptions::overflow_policy.

Definition at line 590 of file Run.h.

push()

bool simaai::neat::Run::push (std::string_view input_name, const std::vector< cv::Mat > & inputs)

Push cv::Mat inputs into a named graph ingress. Use for multi-input graphs.

Definition at line 592 of file Run.h.

push()

bool simaai::neat::Run::push (const TensorList & inputs)

Push Tensor inputs (one per ingress port).

Definition at line 598 of file Run.h.

push()

bool simaai::neat::Run::push (std::string_view input_name, const TensorList & inputs)

Push Tensor inputs into a named graph ingress. Use for multi-input graphs.

Definition at line 600 of file Run.h.

push()

bool simaai::neat::Run::push (const Sample & msgs)

Push full Sample inputs (carrying per-buffer metadata).

Definition at line 606 of file Run.h.

push()

bool simaai::neat::Run::push (std::string_view input_name, const Sample & msgs)

Push full Sample inputs into a named graph ingress. Use for multi-input graphs.

Definition at line 608 of file Run.h.

push_holder()

bool simaai::neat::Run::push_holder (const std::shared_ptr< void > & holder)

Internal: pushes a GstBuffer held by a tensor ref to preserve plugin metadata.

Definition at line 614 of file Run.h.

report()

std::string simaai::neat::Run::report (const RunReportOptions & opt={})

Returns a human-readable formatted report combining stats and diagnostics.

Definition at line 683 of file Run.h.

run()

TensorList simaai::neat::Run::run (const std::vector< cv::Mat > & inputs, int timeout_ms=-1)

One-shot synchronous push+pull from cv::Mat inputs.

Definition at line 649 of file Run.h.

run()

TensorList simaai::neat::Run::run (const TensorList & inputs, int timeout_ms=-1)

One-shot synchronous push+pull from Tensor inputs.

Definition at line 651 of file Run.h.

run()

Sample simaai::neat::Run::run (const Sample & inputs, int timeout_ms=-1)

One-shot synchronous push+pull from Sample inputs.

Definition at line 653 of file Run.h.

running()

bool simaai::neat::Run::running ()

Returns true if the pipeline is in PLAYING state.

Definition at line 580 of file Run.h.

start_measurement()

MeasureScope simaai::neat::Run::start_measurement (const MeasureOptions & opt={})

Start observing a caller-owned push/pull interval without consuming outputs.

Definition at line 656 of file Run.h.

stats()

RunStats simaai::neat::Run::stats ()

Returns end-to-end push/pull/latency stats.

Definition at line 666 of file Run.h.

stop()

void simaai::neat::Run::stop ()

Stop the pipeline immediately (transitions to NULL). After stop, the Run is no longer running.

Definition at line 690 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (const std::vector< cv::Mat > & inputs)

Non-blocking variant of push; returns false immediately if the queue is full.

Definition at line 594 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (std::string_view input_name, const std::vector< cv::Mat > & inputs)

Non-blocking named-ingress variant.

Definition at line 596 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (const TensorList & inputs)

Non-blocking variant.

Definition at line 602 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (std::string_view input_name, const TensorList & inputs)

Non-blocking named-ingress variant.

Definition at line 604 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (const Sample & msgs)

Non-blocking variant.

Definition at line 610 of file Run.h.

try_push()

bool simaai::neat::Run::try_push (std::string_view input_name, const Sample & msgs)

Non-blocking named-ingress variant.

Definition at line 612 of file Run.h.

try_push_holder()

bool simaai::neat::Run::try_push_holder (const std::shared_ptr< void > & holder)

Non-blocking variant of push_holder.

Definition at line 616 of file Run.h.

warmup()

int simaai::neat::Run::warmup (const std::vector< cv::Mat > & inputs, int warm=-1, int timeout_ms=-1)

Run warm warm-up inferences before measurement begins.

Useful for stable performance numbers — first inferences pay one-time setup costs (kernel load, JIT, cache fill). Pass warm = -1 for a sensible default.

Definition at line 663 of file Run.h.

Private Member Functions

enqueue_run_images()

void simaai::neat::Run::enqueue_run_images (const std::vector< cv::Mat > & inputs)

Definition at line 705 of file Run.h.

enqueue_run_samples()

void simaai::neat::Run::enqueue_run_samples (const Sample & inputs)

Definition at line 707 of file Run.h.

enqueue_run_tensors()

void simaai::neat::Run::enqueue_run_tensors (const TensorList & inputs)

Definition at line 706 of file Run.h.

pull_samples_strict()

Sample simaai::neat::Run::pull_samples_strict (int timeout_ms)

Definition at line 709 of file Run.h.

pull_tensors_strict()

TensorList simaai::neat::Run::pull_tensors_strict (int timeout_ms)

Definition at line 708 of file Run.h.

push_holder_impl()

bool simaai::neat::Run::push_holder_impl (const std::shared_ptr< void > & holder, bool block)

Definition at line 712 of file Run.h.

push_impl()

bool simaai::neat::Run::push_impl (const cv::Mat & input, bool block)

Definition at line 710 of file Run.h.

push_impl()

bool simaai::neat::Run::push_impl (const simaai::neat::Tensor & input, bool block)

Definition at line 711 of file Run.h.

push_message_impl()

bool simaai::neat::Run::push_message_impl (const Sample & msg, bool block)

Definition at line 713 of file Run.h.

push_sample_impl()

bool simaai::neat::Run::push_sample_impl (const Sample & msg, bool block)

Definition at line 714 of file Run.h.

require_async_mode()

void simaai::neat::Run::require_async_mode (const char * where)

Definition at line 703 of file Run.h.

require_async_pull_mode()

void simaai::neat::Run::require_async_pull_mode (const char * where)

Definition at line 704 of file Run.h.

Private Member Attributes

core_

std::shared_ptr<runtime::RunCore> simaai::neat::Run::core_

Definition at line 700 of file Run.h.

700 std::shared_ptr<runtime::RunCore> core_;

Private Static Functions

create()

Run simaai::neat::Run::create (InputStream stream, const RunOptions & opt, const struct InputStreamOptions & stream_opt, RunMode mode=RunMode::Async, const std::optional< InputOptions > & tensor_input_opt_for_cv=std::nullopt, pipeline_internal::InputRouteProcessorPtr input_route_processor=nullptr)
static

Definition at line 715 of file Run.h.


The documentation for this class was generated from the following file:


Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.