Session Class
The assembly stage — turns a list of Nodes into a runnable, deterministic pipeline. More...
Declaration
Included Headers
Public Member Typedefs Index
| using | TensorCallback = std::function< bool(const simaai::neat::Tensor &)> |
|
Callback signature used by source-mode pipelines (no input pushed; pipeline produces tensors continuously). More... | |
Friends Index
| struct | simaai::neat::internal::ModelAccess |
Public Constructors Index
| Session (const SessionOptions &opt={}) | |
|
Construct an empty Session with the given options (or defaults). More... | |
| Session (const Session &)=delete | |
|
Non-copyable. More... | |
| Session (Session &&) noexcept | |
|
Move-constructible. More... | |
Public Destructor Index
| ~Session () | |
Public Operators Index
| Session & | operator= (const Session &)=delete |
|
Non-copyable. More... | |
| Session & | operator= (Session &&) noexcept |
|
Move-assignable. More... | |
Public Member Functions Index
| Session & | add (std::shared_ptr< Node > node) |
| Session & | add (const NodeGroup &group) |
|
Append a NodeGroup (a bundle of Nodes) by copy. More... | |
| Session & | add (NodeGroup &&group) |
|
Append a NodeGroup by move (avoids copying internal Node vector). More... | |
| Session & | custom (std::string fragment) |
|
Splice a raw GStreamer launch fragment into the pipeline. More... | |
| Session & | custom (std::string fragment, InputRole role) |
|
Variant that declares the fragment's role (e.g., source vs. sink). More... | |
| void | run () |
|
Run a source-mode pipeline (no inputs pushed; producer Nodes drive the flow). More... | |
| TensorList | run (const std::vector< cv::Mat > &inputs, const RunOptions &opt={}) |
|
One-shot synchronous push+pull from cv::Mat inputs. More... | |
| TensorList | run (const TensorList &inputs, const RunOptions &opt={}) |
| SampleList | run (const SampleList &inputs, const RunOptions &opt={}) |
|
One-shot synchronous push+pull from Sample inputs (carries per-buffer metadata). More... | |
| Run | build (const std::vector< cv::Mat > &inputs, RunMode mode=RunMode::Async, const RunOptions &opt={}) |
|
Build a long-lived Run handle, seeding caps from cv::Mat inputs. More... | |
| Run | build (const TensorList &inputs, RunMode mode=RunMode::Async, const RunOptions &opt={}) |
| Run | build (const SampleList &inputs, RunMode mode=RunMode::Async, const RunOptions &opt={}) |
|
Build variant seeded with full Sample inputs (with per-buffer metadata). More... | |
| SessionReport | validate (const ValidateOptions &opt, const cv::Mat &input) const |
|
Validate the Session against a real input sample without running the pipeline. More... | |
| RtspServerHandle | run_rtsp (const RtspServerOptions &opt) |
| SessionReport | validate (const ValidateOptions &opt={}) const |
| Session & | add_output_tensor (const OutputTensorOptions &opt={}) |
|
Append a tensor-friendly output (auto-inserts convert/scale/caps + sink). More... | |
| std::string | describe (const GraphPrinter::Options &opt={}) const |
|
Returns a hierarchical, human-readable view of the Nodes added so far. More... | |
| std::string | describe_backend (bool insert_boundaries=false) const |
|
Returns the GStreamer launch string the Session would emit at build(). More... | |
| void | set_guard (std::shared_ptr< void > guard) |
|
Attach an external lifetime guard (used by externally-managed runtimes). More... | |
| void | set_tensor_callback (TensorCallback cb) |
|
Set the per-tensor callback used by source-mode run(). More... | |
| void | save (const std::string &path) const |
|
Save the Session's Node list, options, and topology to a JSON file at path. More... | |
| Run | build (const RunOptions &opt={}) |
|
Build a Session as an asynchronous runner without seeding inputs. More... | |
| const std::string & | last_pipeline () const |
|
Returns the GStreamer launch string from the most recent build() call. More... | |
Private Member Functions Index
| void | build_cached_source () |
Private Member Attributes Index
| std::vector< std::shared_ptr< Node > > | nodes_ |
| std::vector< GroupMeta > | groups_ |
| std::string | last_pipeline_ |
| std::shared_ptr< void > | guard_ |
| std::shared_ptr< void > | verbose_guard_ |
| SessionOptions | opt_ {} |
| TensorCallback | tensor_cb_ |
| std::atomic< uint64_t > | nodes_version_ {0} |
| std::unique_ptr< BuiltState > | built_ |
| std::unique_ptr< RunCache > | run_cache_ |
| uint64_t | built_version_ = 0 |
| std::shared_ptr< const pipeline_internal::InputRouteProcessor > | input_route_processor_ |
Public Static Functions Index
| static Session | load (const std::string &path) |
|
Reconstruct a Session from a previously-saved JSON file. More... | |
Description
The assembly stage — turns a list of Nodes into a runnable, deterministic pipeline.
A Session does five jobs when you call build():
- Composition — collects Nodes and NodeGroups in the order you added them.
- Validation — runs structural contracts (no empty pipeline, no null nodes, sink last, etc.) and surfaces issues as a structured SessionReport.
- Compilation — translates the Node sequence into a deterministic GStreamer pipeline string with stable element names like n3_videoconvert.
- Negotiation — hands the pipeline to GStreamer, which negotiates caps between adjacent elements (formats, resolutions, framerates, memory layouts).
- Materialization — instantiates the actual GStreamer elements, transitions through NULL → READY → PAUSED state, and returns a Run handle.
Sessions are non-copyable but movable. They are not thread-safe — build a Session on one thread, then hand the resulting Run to wherever it's needed.
- See Also
Run for the runtime handle this produces
- See Also
Model — the simplified entry point that wraps a Session for users who don't need composition flexibility
- See Also
SessionReport for the structured error/diagnostics surface
- See Also
RtspServerHandle for server-mode Sessions
Definition at line 140 of file Session.h.
Public Member Typedefs
TensorCallback
|
Callback signature used by source-mode pipelines (no input pushed; pipeline produces tensors continuously).
Definition at line 144 of file Session.h.
Friends
simaai::neat::internal::ModelAccess
|
Definition at line 295 of file Session.h.
Public Constructors
Session()
| explicit |
Session()
| delete |
Session()
Public Operators
operator=()
| delete |
operator=()
Public Member Functions
add()
|
add()
|
add()
|
add_output_tensor()
|
Append a tensor-friendly output (auto-inserts convert/scale/caps + sink).
Convenience for "I want my output as a Tensor in a specific format/shape." Equivalent to adding VideoConvert, VideoScale, Caps, and Output Nodes manually but encapsulated.
- Returns
*this to allow chaining.
build()
|
Build a long-lived Run handle, seeding caps from cv::Mat inputs.
- Parameters
-
inputs One Mat per ingress port; used for build-time adaptation.
mode Async (default; pipeline runs continuously) or Sync.
opt Runtime options (queue depth, overflow policy).
- Exceptions
-
<a href="/reference/cppapi/classes/simaai-neat-sessionerror">SessionError</a> on validation or build failure.
build()
|
build()
|
build()
|
Build a Session as an asynchronous runner without seeding inputs.
Use this for source pipelines (Sessions whose first Node is a producer like RTSPInput or StillImageInput — no push() from user code needed). Push pipelines should prefer build(inputs, ...) so caps can be derived from the actual input.
custom()
|
Splice a raw GStreamer launch fragment into the pipeline.
Useful for one-off experiments, third-party plugins NEAT doesn't wrap, or GStreamer features (tee, selector, dynamic pads) that are awkward to model as Nodes. The trade-off: you lose deterministic naming for the spliced fragment. Use sparingly.
- Parameters
-
fragment Raw GStreamer launch string (e.g., "identity silent=false ! videocrop ...").
- Returns
*this to allow chaining.
custom()
|
describe()
|
describe_backend()
|
Returns the GStreamer launch string the Session would emit at build().
Paste into gst-launch-1.0 to reproduce the pipeline outside the framework — invaluable for debugging caps issues or isolating "is this NEAT's bug or GStreamer's?"
- Parameters
-
insert_boundaries If true, inserts diagnostic identity probes between Nodes.
last_pipeline()
| inline |
Returns the GStreamer launch string from the most recent build() call.
run()
|
Run a source-mode pipeline (no inputs pushed; producer Nodes drive the flow).
Used in conjunction with set_tensor_callback(). The pipeline runs until end-of-stream or until the callback returns false.
- Exceptions
-
<a href="/reference/cppapi/classes/simaai-neat-sessionerror">SessionError</a> on validation or runtime failure (with structured SessionReport).
run()
|
run()
|
run()
|
run_rtsp()
|
Build the Session and run it as an RTSP server.
The Session must terminate in an H.264 encoded stream. The returned handle owns a live RTSP server publishing the pipeline's output to network clients. Stop the server by calling handle.stop() or letting the handle go out of scope.
- Parameters
-
opt RTSP server options (mount point, port, RTP port range).
- Returns
Live RtspServerHandle exposing the broadcast URL.
save()
|
set_guard()
|
set_tensor_callback()
|
validate()
|
Validate the Session against a real input sample without running the pipeline.
Runs structural contracts AND build-time adaptation against the input. Reports whether the pipeline would accept this input shape/format and what conversions would be needed. Useful in CI to catch shape mismatches before deploying.
validate()
|
Validate the Session structurally without running.
Runs all built-in contracts (NonEmptyPipeline, NoNullNodes, SinkLastForRun, etc.) and returns a structured SessionReport. Cheaper than build() because it doesn't instantiate GStreamer state. Useful in unit tests and CI.
- Returns
SessionReport carrying any contract failures, with error_code and repro_note.
Private Member Attributes
built_
|
built_version_
|
groups_
|
guard_
|
input_route_processor_
|
last_pipeline_
|
nodes_
|
nodes_version_
|
opt_
|
run_cache_
|
tensor_cb_
|
Definition at line 334 of file Session.h.
verbose_guard_
The documentation for this class was generated from the following file:
Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.