Run Class

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

Declaration

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

Included Headers

#include <Run.h>

Friends Index

class	MeasureScope
class	Graph

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

bool	can_push () const
	Returns true if the input side accepts pushes (not closed). More...
bool	can_pull () const
	Returns true if the output side may produce more samples (pipeline not at EOS). More...
bool	running () 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...
bool	push (const std::vector< cv::Mat > &inputs)
	Push cv::Mat inputs into the pipeline. More...
bool	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. More...
bool	try_push (const std::vector< cv::Mat > &inputs)
	Non-blocking variant of push; returns false immediately if the queue is full. More...
bool	try_push (std::string_view input_name, const std::vector< cv::Mat > &inputs)
	Non-blocking named-ingress variant. More...
bool	push (const TensorList &inputs)
	Push Tensor inputs (one per ingress port). More...
bool	push (std::string_view input_name, const TensorList &inputs)
	Push Tensor inputs into a named graph ingress. Use for multi-input graphs. More...
bool	try_push (const TensorList &inputs)
	Non-blocking variant. More...
bool	try_push (std::string_view input_name, const TensorList &inputs)
	Non-blocking named-ingress variant. More...
bool	push (const Sample &msgs)
	Push full Sample inputs (carrying per-buffer metadata). More...
bool	push (std::string_view input_name, const Sample &msgs)
	Push full Sample inputs into a named graph ingress. Use for multi-input graphs. More...
bool	try_push (const Sample &msgs)
	Non-blocking variant. More...
bool	try_push (std::string_view input_name, const Sample &msgs)
	Non-blocking named-ingress variant. More...
bool	push_holder (const std::shared_ptr< void > &holder)
	Internal: pushes a GstBuffer held by a tensor ref to preserve plugin metadata. More...
bool	try_push_holder (const std::shared_ptr< void > &holder)
	Non-blocking variant of push_holder. More...
void	close_input ()
	Send EOS into the pipeline. More...
PullStatus	pull (int timeout_ms, Sample &out, PullError *err=nullptr)
	Pull the next output sample with a structured status return. More...
PullStatus	pull (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...
TensorList	pull_tensors (int timeout_ms=-1)
	Pull and unpack the next sample as a TensorList. More...
TensorList	pull_tensors (std::string_view output_name, int timeout_ms=-1)
	Pull and unpack from a named graph output as a TensorList. More...
Sample	pull_samples (int timeout_ms=-1)
	Pull the next sample as a Sample (preserves per-sample metadata). More...
Sample	pull_samples (std::string_view output_name, int timeout_ms=-1)
	Pull samples from a named graph output (preserves per-sample metadata). More...
TensorList	run (const std::vector< cv::Mat > &inputs, int timeout_ms=-1)
	One-shot synchronous push+pull from cv::Mat inputs. More...
TensorList	run (const TensorList &inputs, int timeout_ms=-1)
	One-shot synchronous push+pull from Tensor inputs. More...
Sample	run (const Sample &inputs, int timeout_ms=-1)
	One-shot synchronous push+pull from Sample inputs. More...
MeasureScope	start_measurement (const MeasureOptions &opt={})
	Start observing a caller-owned push/pull interval without consuming outputs. More...
MeasureScope	start_measurement (bool include_plugin_latency)
	Convenience overload: false = E2E latency/throughput only, true = include plugin latency. More...
std::string	last_error () const
	Returns the most recent runtime error string (empty if no error occurred). More...
void	stop ()
	Stop execution and initiate pipeline teardown. More...
void	close ()
	Alias for stop(). Resource release may complete asynchronously. More...

Private Member Functions Index

void	require_async_mode (const char *where) const
void	require_async_pull_mode (const char *where) const
void	enqueue_run_images (const std::vector< cv::Mat > &inputs)
void	enqueue_run_tensors (const TensorList &inputs)
void	enqueue_run_samples (const Sample &inputs)
TensorList	pull_tensors_strict (int timeout_ms)
Sample	pull_samples_strict (int timeout_ms)
bool	push_impl (const cv::Mat &input, bool block)
bool	push_impl (const simaai::neat::Tensor &input, bool block)
bool	push_holder_impl (const std::shared_ptr< void > &holder, bool block)
bool	push_message_impl (const Sample &msg, bool block)
bool	push_sample_impl (const Sample &msg, bool block)

Private Member Attributes Index

std::shared_ptr< runtime::RunCore >	core_

Private Static Functions Index

static 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)

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 628 of file Run.h.

Friends

Graph

friend class Graph

Definition at line 759 of file Run.h.

MeasureScope

friend class MeasureScope

Definition at line 735 of file Run.h.

Public Constructors

Run()

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

default

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

Definition at line 631 of file Run.h.

Run()

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

delete

Non-copyable.

Definition at line 632 of file Run.h.

Run()

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

noexcept

Move-constructible.

Definition at line 635 of file Run.h.

Private Constructors

Run()

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

explicit

Definition at line 742 of file Run.h.

Public Destructor

~Run()

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

Cleanly tears down the pipeline.

Definition at line 637 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 640 of file Run.h.

operator=()

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

delete

Non-copyable.

Definition at line 633 of file Run.h.

operator=()

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

noexcept

Move-assignable.

Definition at line 636 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 644 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 642 of file Run.h.

close()

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

Alias for stop(). Resource release may complete asynchronously.

Definition at line 732 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 685 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 648 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 726 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 650 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 693 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 700 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 703 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 705 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 711 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 713 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 707 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 709 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 656 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 658 of file Run.h.

push()

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

Push Tensor inputs (one per ingress port).

Definition at line 664 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 666 of file Run.h.

push()

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

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

Definition at line 672 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 674 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 680 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 715 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 717 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 719 of file Run.h.

running()

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

Returns true if the pipeline is in PLAYING state.

Definition at line 646 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 722 of file Run.h.

start_measurement()

MeasureScope simaai::neat::Run::start_measurement (bool include_plugin_latency)

Convenience overload: false = E2E latency/throughput only, true = include plugin latency.

Definition at line 724 of file Run.h.

stop()

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

Stop execution and initiate pipeline teardown.

Resource release may complete asynchronously after this returns.

Definition at line 730 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 660 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 662 of file Run.h.

try_push()

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

Non-blocking variant.

Definition at line 668 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 670 of file Run.h.

try_push()

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

Non-blocking variant.

Definition at line 676 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 678 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 682 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 745 of file Run.h.

enqueue_run_samples()

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

Definition at line 747 of file Run.h.

enqueue_run_tensors()

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

Definition at line 746 of file Run.h.

pull_samples_strict()

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

Definition at line 749 of file Run.h.

pull_tensors_strict()

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

Definition at line 748 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 752 of file Run.h.

push_impl()

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

Definition at line 750 of file Run.h.

push_impl()

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

Definition at line 751 of file Run.h.

push_message_impl()

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

Definition at line 753 of file Run.h.

push_sample_impl()

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

Definition at line 754 of file Run.h.

require_async_mode()

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

Definition at line 743 of file Run.h.

require_async_pull_mode()

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

Definition at line 744 of file Run.h.

Private Member Attributes

core_

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

Definition at line 740 of file Run.h.

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 755 of file Run.h.

---

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

• Run.h

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.