Class anira::ModelConfig#

class ModelConfig#

The model: one entry per export (an engine, and a provider when pinned; a file or bytes) with what that export calls each tensor and how it lays out its axes, the input and output specs, the default engine, the state, the instance ceiling and the anchor. Move-only.

Public Functions

inline ModelConfig()#
Throws:

Error – when the C entry refuses the call; the status says why.

inline ~ModelConfig()#
ModelConfig(const ModelConfig&) = delete#
ModelConfig &operator=(const ModelConfig&) = delete#
inline ModelConfig(ModelConfig &&other) noexcept#
inline ModelConfig &operator=(ModelConfig &&other) noexcept#
inline uint32_t add_model_path(EngineKind engine, const std::filesystem::path &path)#

A file for a built-in engine; returns the entry index.

inline uint32_t add_model_path(std::string_view engine_id, const std::filesystem::path &path)#

A file for a custom engine registered under a reverse-URI name (ANIRA_ENGINE_CUSTOM with the id).

inline uint32_t add_model(std::string_view engine_id)#

An entry without a source for a custom engine that declares ANIRA_ENGINE_FLAG_NEEDS_NO_MODEL (a NULL path): the engine computes without a model file.

inline uint32_t add_model_bytes(EngineKind engine, std::span<const std::byte> bytes, anira_bytes_ownership ownership = ANIRA_BYTES_COPY, anira_bytes_release_fn release = nullptr, void *ctx = nullptr)#

Bytes for a built-in engine: copied, or borrowed until the last carrier of the bytes dies (this config, a set_model_bytes replacement, later the handler that copied the config), when release(bytes, ctx), if given, is called exactly once.

inline uint32_t add_model_bytes(std::string_view engine_id, std::span<const std::byte> bytes, anira_bytes_ownership ownership = ANIRA_BYTES_COPY, anira_bytes_release_fn release = nullptr, void *ctx = nullptr)#
inline ModelConfig &set_model_bytes(uint32_t index, std::span<const std::byte> bytes, anira_bytes_ownership ownership = ANIRA_BYTES_COPY, anira_bytes_release_fn release = nullptr, void *ctx = nullptr)#

Replaces an entry’s source with bytes, e.g. to patch a path a JSON file named.

inline uint32_t model_count() const noexcept#
inline EngineRef model_engine(uint32_t index) const noexcept#

The entry’s engine as the pair (anira_model_config_model_engine): ANIRA_ENGINE_CUSTOM with the id for a custom one; {ANIRA_ENGINE_NONE, empty} for an index out of range. The id is owned by the config and valid until it is mutated, moved or destroyed.

inline ProviderRef model_provider(uint32_t index) const noexcept#

The provider the entry is pinned to as the pair (anira_model_config_model_provider): ANIRA_PROVIDER_CUSTOM with the name for a custom pin, ANIRA_PROVIDER_NONE for an entry without a pin and for an index out of range. The name is owned by the config.

inline std::string_view model_path(uint32_t index) const#

The entry’s path, owned by the config and valid until it is mutated, moved or destroyed.

Throws:

Error{ANIRA_ERROR_INVALID_STATE} – on a bytes entry and on an entry without a source (add_model(engine_id)), Error{ANIRA_ERROR_INVALID_ARGUMENT} for an index out of range.

inline std::span<const std::byte> model_bytes(uint32_t index) const#

The entry’s bytes; the span is invalidated by set_model_bytes on that entry and by the config’s destruction.

Throws:

Error – on a path entry.

inline ModelConfig &model_provider(uint32_t index, Provider provider)#

Pins the entry to the provider its file is built for (an ExecuTorch export lowered for a provider (an ExecuTorch delegate), an ONNX Runtime .ort compiled for an execution provider): a provider of the enum here, a custom name through the string overload. Only a candidate naming that provider runs a pinned entry; an entry without a pin runs on any provider of its engine, the candidate deciding. Two entries of one engine may coexist when their pins differ. ANIRA_PROVIDER_NONE unpins; ANIRA_PROVIDER_CPU pins to the CPU path.

inline ModelConfig &model_provider(uint32_t index, std::string_view provider_id)#

Pins the entry to a custom provider, by its name in the engine’s own vocabulary (ANIRA_PROVIDER_CUSTOM with the name).

inline ModelConfig &tensor_name(uint32_t index, std::string_view canonical, std::string_view export_name)#

What this entry’s export calls the tensor you named canonical (binds it by name).

inline ModelConfig &tensor_layout(uint32_t index, std::string_view canonical, std::span<const uint32_t> axes)#

The order in which this entry’s export holds the tensor’s axes: the spec axis at each file position, ANIRA_AXIS_INSERT for a unit axis the spec lacks. An empty span clears.

template<class Ext>
inline ModelConfig &model_ext(uint32_t index, const Ext &value)#

An extension on one entry, e.g. ext::Entry{“decode”}.

inline ModelConfig &model_ext_json(uint32_t index, std::string_view kind, std::string_view utf8)#
inline uint32_t input_count() const noexcept#

The number of input specs, State specs included.

inline uint32_t output_count() const noexcept#
inline SpecView input_spec(uint32_t i) const#

The config’s own copy of input spec i, valid until the config is mutated, moved or destroyed.

Throws:

Error{ANIRA_ERROR_INVALID_ARGUMENT} – out of range.

inline SpecView output_spec(uint32_t i) const#
inline EngineRef default_engine() const noexcept#

The default engine as the pair (anira_model_config_default_engine): ANIRA_ENGINE_NONE for plan 0, ANIRA_ENGINE_CUSTOM with the id for a custom one.

inline ProviderRef default_provider() const noexcept#

The default provider as the pair (anira_model_config_default_provider): ANIRA_PROVIDER_NONE for none, ANIRA_PROVIDER_CUSTOM with the name for a custom one.

inline anira_model_state state() const noexcept#

As set; a model with a declared State pair runs as ANIRA_MODEL_STATEFUL anyway.

inline uint32_t max_instances() const noexcept#

As set: a count, or ANIRA_INSTANCES_AUTO (the default, the pool’s thread count once a handler is prepared).

inline std::string_view anchor() const noexcept#

The anchor’s canonical name as set; empty for the default.

inline std::string_view tensor_name(uint32_t index, std::string_view canonical) const#

What entry index calls the tensor; empty when it binds the tensor positionally.

Throws:

Error{ANIRA_ERROR_INVALID_ARGUMENT} – for an index out of range.

inline std::vector<uint32_t> tensor_layout(uint32_t index, std::string_view canonical) const#

The axis order entry index holds the tensor in; empty for the spec’s order.

Throws:

Error{ANIRA_ERROR_INVALID_ARGUMENT} – for an index out of range or an empty name.

template<class Ext>
inline std::optional<Ext> model_ext(uint32_t index) const#

The extension of kind Ext on entry index, copied out (ext::Entry: the entry point); nullopt when the entry carries none.

Throws:

Error{ANIRA_ERROR_INVALID_ARGUMENT} – for an index out of range.

inline ModelConfig &input(const TensorSpec &spec)#

Appends an input spec (copied; the spec may be destroyed afterwards).

inline ModelConfig &output(const TensorSpec &spec)#
inline ModelConfig &default_engine(EngineKind engine)#

The engine the handler starts on (anira_model_config_set_default_engine): a built-in engine, or ANIRA_ENGINE_NONE for plan 0.

inline ModelConfig &default_engine(std::string_view engine_id)#

A custom engine the handler starts on, by its id (ANIRA_ENGINE_CUSTOM with the id).

inline ModelConfig &default_provider(Provider provider)#

The provider the handler starts on beside the default engine: the first plan of the default engine (of any engine without one) on this provider. The default engine’s rule holds: ANIRA_ERROR_CONFIG at create when no entry could run on it (each pinned to another provider); a plan table without such a plan starts as without it, with one Warning at prepare (anira_model_config_set_default_provider). A provider of the enum here, a custom name through the string overload; ANIRA_PROVIDER_NONE sets none.

inline ModelConfig &default_provider(std::string_view provider_id)#

A custom provider the handler starts on, by its name in the engine’s own vocabulary (ANIRA_PROVIDER_CUSTOM with the name).

inline ModelConfig &state(anira_model_state value)#
inline ModelConfig &max_instances(uint32_t value)#

The shared instances of a stateless model, at least 1, or ANIRA_INSTANCES_AUTO (the default): as many as the inference pool has threads. Each is a full copy of the model in memory; 1 keeps one.

inline ModelConfig &anchor(std::string_view canonical)#

The streamed tensor that is the model’s clock, by canonical name; empty = default.

template<class Ext>
inline ModelConfig &ext(const Ext &value)#
inline ModelConfig &ext_json(std::string_view kind, std::string_view utf8)#
inline std::string to_json() const#

The model file in 3.x spelling, fixed key order.

inline bool upgraded() const noexcept#

Whether from_json/from_file read a 2.x document.

inline std::optional<ContractHandle> take_legacy_contract()#

The Hard contract a 2.x upgrade held back (max_inference_time, warm_up, blocking_ratio); once, and only after an upgrade.

inline const anira_model_config *native() const noexcept#
inline anira_model_config *native() noexcept#

Public Static Functions

static inline ModelConfig from_json(std::string_view utf8, std::string_view base_dir = {})#

A model file (section 8.1); relative paths resolve against base_dir. A 2.x document is upgraded: upgraded() is true and take_legacy_contract() carries its Hard contract.

static inline ModelConfig from_file(const std::filesystem::path &path)#

Reads a model file; its directory is the base_dir.