Contracts

Builder-level validation rules and reports. More...

Classes Index

struct	ValidationContext
	Context passed to contracts during validation. More...
class	Contract
	A single validation rule applied to an ordered node list. More...
class	ContractRegistry
	Holds a set of Contracts and runs them to produce a ValidationReport. More...
struct	ContractPortSpec
	Per-port contract: the shape/type/segment requirements for one input or output. More...
struct	ContractFieldSpec
	Per-field contract: where the field value comes from and the override policy. More...
struct	NodeContractDefinition
	Bundle of port and field specs that fully describes a Node's contract. More...
struct	ValidationIssue
	A single reported issue from a Contract. More...
class	ValidationReport
	Report produced by running a ContractRegistry. More...

Enumerations Index

enum class	MemoryContract { ... }
	How a Node (or Graph) wants buffer memory to be sourced/handed back. More...
enum class	CapsMemory { ... }
	Memory class to advertise in GStreamer caps. More...
enum class	ContractFieldSource { ... }
	Where the value of a contract field originates. More...
enum class	ContractOverridePolicy { ... }
	Whether the Builder may override a contract field at build time. More...
enum class	ValidationSeverity { ... }
	Severity level for validation issues. More...

Functions Index

std::shared_ptr< Contract >	NonEmptyPipeline ()
	Ensures the node list is not empty. More...
std::shared_ptr< Contract >	NoNullNodes ()
	Ensures there are no null node pointers in the node list. More...
std::shared_ptr< Contract >	SinkLastForRun (std::string sink_kind="Output")
	Ensures the configured sink kind exists and is last when ctx.mode == Run. More...
std::shared_ptr< Contract >	RtspRequiresSource (std::string source_kind="StillImageInput")
	Ensures an RTSP source node exists when ctx.mode == Rtsp. More...
ContractRegistry	DefaultRegistry ()
	Reasonable default set of builder-level contracts. More...

Description

Builder-level validation rules and reports.

Enumerations

CapsMemory

enum class simaai::neat::CapsMemory

strong

Memory class to advertise in GStreamer caps.

Enumeration values

Any	Don't constrain memory class in caps (= 0)
SystemMemory	Force caps to advertise memory:SystemMemory

Any means "don't constrain in caps"; SystemMemory forces the caps to carry memory:SystemMemory so upstream/downstream negotiation picks CPU-mappable buffers.

Definition at line 54 of file ContractTypes.h.

54enum class CapsMemory {

55 Any = 0,

56 SystemMemory,

57};

ContractFieldSource

enum class simaai::neat::ContractFieldSource

strong

Where the value of a contract field originates.

Enumeration values

Fixed	Value is hard-coded in the contract definition
BuilderOption	Value comes from a builder-level option/argument
ModelOnly	Value is supplied by the model file (e.g., MPK contract)
InputOnly	Value is determined by external input only
UpstreamOnly	Value is derived from the upstream Node's output spec
GraphOwned	Value is owned by the enclosing Graph (cross-Node)

Used by the Builder to decide whether a field is fully bound at definition time, supplied by a builder option, derived from upstream caps, baked into a model file, or owned by the Graph as a whole.

Definition at line 31 of file NodeContractDefinition.h.

31enum class ContractFieldSource {

32 Fixed,

33 BuilderOption,

34 ModelOnly,

35 InputOnly,

36 UpstreamOnly,

37 GraphOwned,

38};

ContractOverridePolicy

enum class simaai::neat::ContractOverridePolicy

strong

Whether the Builder may override a contract field at build time.

Enumeration values

Forbidden	Field cannot be overridden; attempts are validation errors
BuilderOnly	Builder code may override; user-facing API may not

Definition at line 44 of file NodeContractDefinition.h.

44enum class ContractOverridePolicy {

45 Forbidden,

46 BuilderOnly,

47};

MemoryContract

enum class simaai::neat::MemoryContract

strong

How a Node (or Graph) wants buffer memory to be sourced/handed back.

Enumeration values

RequireSystemMemoryMappable	Must be CPU-mappable (typically SystemMemory); violations are hard errors (= 0)
PreferDeviceZeroCopy	Prefer device/zero-copy; runner may avoid forcing SystemMemory but still reports mismatches
AllowEitherButReport	Allow either; if non-mappable, return empty payload with explicit reason + location

Drives the runner's behavior at output time and contributes to caps negotiation: requiring CPU-mappable memory forces a (potentially copying) conversion, while PreferDeviceZeroCopy lets the runner keep device memory whenever possible.

Definition at line 30 of file ContractTypes.h.

30enum class MemoryContract {

32 RequireSystemMemoryMappable = 0,

33

35 PreferDeviceZeroCopy,

36

38 AllowEitherButReport,

39};

ValidationSeverity

enum class simaai::neat::ValidationSeverity

strong

Severity level for validation issues.

Enumeration values

Info	Informational only; never blocks a run (= 0)
Warning	Soft contract violation; pipeline may still run
Error	Hard contract violation; pipeline must not run

Definition at line 29 of file ValidationReport.h.

29enum class ValidationSeverity {

30 Info = 0,

31 Warning,

32 Error,

33};

Functions

DefaultRegistry()

ContractRegistry simaai::neat::validators::DefaultRegistry ()

inline

Reasonable default set of builder-level contracts.

Bundles NonEmptyPipeline, NoNullNodes, SinkLastForRun, and RtspRequiresSource into a fresh registry. Keep this purely structural (no GStreamer); domain-specific contracts should be added on top.

Returns

New ContractRegistry populated with the default contracts.

Definition at line 213 of file Validators.h.

213inline ContractRegistry DefaultRegistry() {

214 ContractRegistry reg;

215 reg.add(NonEmptyPipeline());

216 reg.add(NoNullNodes());

217 reg.add(SinkLastForRun());

218 reg.add(RtspRequiresSource());

219 return reg;

220}

NonEmptyPipeline()

std::shared_ptr< Contract > simaai::neat::validators::NonEmptyPipeline ()

inline

Ensures the node list is not empty.

Issues EMPTY_PIPELINE error when validated against an empty node list.

Returns

Shared pointer to a fresh Contract instance.

Definition at line 42 of file Validators.h.

42inline std::shared_ptr<Contract> NonEmptyPipeline() {

43 class C final : public Contract {

44 public:

45 std::string id() const override {

46 return "NonEmptyPipeline";

47 }

48 std::string description() const override {

49 return "Pipeline must contain at least one node.";

50 }

51

52 void validate(std::span<const std::shared_ptr<Node>> nodes, const ValidationContext& ctx,

53 ValidationReport& r) const override {

54 (void)ctx;

55 if (nodes.empty()) {

56 r.add_error(id(), "EMPTY_PIPELINE", "No nodes were added to the pipeline.");

57 }

58 }

59 };

60 return std::make_shared<C>();

61}

NoNullNodes()

std::shared_ptr< Contract > simaai::neat::validators::NoNullNodes ()

inline

Ensures there are no null node pointers in the node list.

Issues a NULL_NODE error per offending index.

Returns

Shared pointer to a fresh Contract instance.

Definition at line 71 of file Validators.h.

71inline std::shared_ptr<Contract> NoNullNodes() {

72 class C final : public Contract {

73 public:

74 std::string id() const override {

75 return "NoNullNodes";

76 }

77 std::string description() const override {

78 return "All nodes must be non-null shared_ptr.";

79 }

80

81 void validate(std::span<const std::shared_ptr<Node>> nodes, const ValidationContext& ctx,

82 ValidationReport& r) const override {

83 (void)ctx;

84 for (int i = 0; i < static_cast<int>(nodes.size()); ++i) {

85 if (!nodes[static_cast<std::size_t>(i)]) {

86 r.add_error(id(), "NULL_NODE", "Null node pointer in pipeline node list.", i);

87 }

88 }

89 }

90 };

91 return std::make_shared<C>();

92}

RtspRequiresSource()

std::shared_ptr< Contract > simaai::neat::validators::RtspRequiresSource (std::string source_kind="StillImageInput")

inline

Ensures an RTSP source node exists when ctx.mode == Rtsp.

Builder-level: we only check presence of StillImageInput (or another configured kind). Issues RTSP_SOURCE_MISSING if no Node of the expected kind is found in the node list.

Parameters

source_kind

The Node kind expected to act as the RTSP source.

Returns

Shared pointer to a fresh Contract instance.

Definition at line 162 of file Validators.h.

162inline std::shared_ptr<Contract> RtspRequiresSource(std::string source_kind = "StillImageInput") {

163 class C final : public Contract {

164 public:

165 explicit C(std::string k) : src_kind_(std::move(k)) {}

166 std::string id() const override {

167 return "RtspRequiresSource";

168 }

169 std::string description() const override {

170 return "RTSP mode requires a server-side source node (e.g., StillImageInput).";

171 }

172

173 void validate(std::span<const std::shared_ptr<Node>> nodes, const ValidationContext& ctx,

174 ValidationReport& r) const override {

175 if (ctx.mode != ValidationContext::Mode::Rtsp)

176 return;

177

178 bool found = false;

179 for (int i = 0; i < static_cast<int>(nodes.size()); ++i) {

180 const auto& n = nodes[static_cast<std::size_t>(i)];

181 if (n && n->kind() == src_kind_) {

182 found = true;

183 break;

184 }

185 }

186

187 if (!found) {

188 r.add_error(id(), "RTSP_SOURCE_MISSING",

189 "RTSP mode requires a node of kind \"" + src_kind_ + "\".", -1, src_kind_, "");

190 }

191 }

192

193 private:

194 std::string src_kind_;

195 };

196 return std::make_shared<C>(std::move(source_kind));

197}

SinkLastForRun()

std::shared_ptr< Contract > simaai::neat::validators::SinkLastForRun (std::string sink_kind="Output")

inline

Ensures the configured sink kind exists and is last when ctx.mode == Run.

This is the builder-level version of the "sink last" contract described in the architecture. Issues SINK_NOT_LAST if the last Node isn't of the expected kind, and MULTIPLE_SINKS if a sink-kind Node is found earlier in the chain.

Parameters

sink_kind

The Node kind expected as the terminal (default "Output").

Returns

Shared pointer to a fresh Contract instance.

Definition at line 106 of file Validators.h.

106inline std::shared_ptr<Contract> SinkLastForRun(std::string sink_kind = "Output") {

107 class C final : public Contract {

108 public:

109 explicit C(std::string kind) : sink_kind_(std::move(kind)) {}

110 std::string id() const override {

111 return "SinkLastForRun";

112 }

113 std::string description() const override {

114 return "When running, the pipeline must end with the terminal appsink node.";

115 }

116

117 void validate(std::span<const std::shared_ptr<Node>> nodes, const ValidationContext& ctx,

118 ValidationReport& r) const override {

119 if (ctx.mode != ValidationContext::Mode::Run)

120 return;

121 if (nodes.empty())

122 return;

123

124 int last_idx = static_cast<int>(nodes.size()) - 1;

125 const auto& last = nodes.back();

126 const std::string last_kind = last ? last->kind() : "";

127

128 // Require sink kind last.

129 if (!last || last_kind != sink_kind_) {

130 r.add_error(id(), "SINK_NOT_LAST", "Last node must be " + sink_kind_ + " for run().",

131 last_idx, last_kind, last ? last->user_label() : "");

132 }

133

134 // Disallow additional sinks earlier (best-effort sanity).

135 for (int i = 0; i < last_idx; ++i) {

136 const auto& n = nodes[static_cast<std::size_t>(i)];

137 if (n && n->kind() == sink_kind_) {

138 r.add_error(id(), "MULTIPLE_SINKS",

139 "Found " + sink_kind_ + " before the end of the pipeline.", i, n->kind(),

140 n->user_label());

141 }

142 }

143 }

144

145 private:

146 std::string sink_kind_;

147 };

148 return std::make_shared<C>(std::move(sink_kind));

149}

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.