sources/gst-plugins/gst-nvmodelmux/gstnvmodelmux_priv.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef __DEEPSTREAM_MULTIMODEL_APP_H__
#define __DEEPSTREAM_MULTIMODEL_APP_H__
 
#include <gst/gst.h>
#include <glib.h>
 
#include "nvdsmeta_schema.h"      /* InferenceProvenanceMeta (public schema struct). The
                                   * NVDS_CUSTOM_MSG_INFERENCE_PROVENANCE meta-type enum
                                   * lives in nvdsmeta.h (pulled in via gstnvdsmeta.h) --
                                   * a consumer needs BOTH headers. */
#include "gstnvmodelmux_perf.h"   /* ModelMuxPerf / ModelMuxPerfCounter perf-metrics module */
 
G_BEGIN_DECLS
 
#define MM_MAX_STREAMS_DEFAULT   16
#define MM_MAX_BATCH             1024   /* hard cap on batch-size (sizes every internal mux) */
#define MM_MAX_MODELS            32
#define MM_DEFAULT_REST_PORT     9000
#define MM_DEFAULT_REST_IP       "0.0.0.0"
 
/* Model versions are POSITIVE INTEGERS ("1", "2", ...), matching Triton's model-repository
 * convention (numbered version dirs; highest = latest). The first version is "1"; model/load
 * auto-increments to max+1. A model is identified by (name, version), joined into a canonical
 * instance KEY "name@version" used as the pool / limbo-map hash key, so multiple versions of
 * one name coexist as distinct ModelBins. */
#define MM_MODEL_VERSION_DEFAULT "1"
#define MM_MODEL_KEY_SEP '@'
 
/* Canonical batched-mux geometry. Applied to the nvmultiurisrcbin input mux and
 * mirrored by the per-model + combined muxes, so all batches share resolution.
 * (Decided at runtime; not user config.) */
/* GIE position of a stage. Values match nvinfer's process-mode (1 = primary/full
 * frame, 2 = secondary/objects); shared so the element, the control plane and the
 * secondary chain all test the same constants. */
#define MM_PROCESS_MODE_PGIE     1
#define MM_PROCESS_MODE_SGIE     2
 
/* Offset added to a SHADOW lane's gie id. A model's configured gie-unique-id names its
 * PRIMARY lane (that is the id a downstream secondary targets); the A/B twin must still
 * be distinguishable in the object meta, so it takes id + this. Matches the Shadow
 * pool's historical base of 100, so ids look the same as they always did. */
#define MM_SHADOW_GIE_OFFSET     100
 
#define MM_MUX_WIDTH             1920
#define MM_MUX_HEIGHT            1080
#define MM_MUX_PUSH_TIMEOUT      33333
 
/* ================================================================== */
/* Pipeline-wide routing revision                                      */
/*                                                                     */
/* routing_revision is the CAS token a controller sends back as        */
/* if_revision, so there may only ever be ONE of it per pipeline: a    */
/* per-stage counter would let a route applied at the secondary leave  */
/* the primary's number untouched, and a controller holding that stale */
/* number would win a compare-and-swap it should have lost.            */
/*                                                                     */
/* Every nvmodelmux stage therefore points at the SAME counter. The    */
/* stages find each other through a GstContext -- GStreamer's own      */
/* mechanism for sharing one live object between element instances in  */
/* a pipeline (the same way GstGLDisplay is shared): the first stage   */
/* to reach READY posts need-context, gets no answer, creates the      */
/* counter and posts have-context; the pipeline caches that context    */
/* and hands it to every other stage, whose need-context is then       */
/* answered synchronously from the cache. No shared globals, no        */
/* assumption about which stage comes up first, and a stage in a       */
/* pipeline of its own simply owns the counter alone.                  */
/* ================================================================== */
 
#define MODELMUX_CONTEXT_TYPE_ROUTING "nvidia.deepstream.modelmux.routing"
 
#define MODELMUX_CONTEXT_FIELD_REV    "revision"
 
typedef struct _ModelMuxRevShared ModelMuxRevShared;
 
#define MODELMUX_TYPE_REV_SHARED (modelmux_rev_shared_get_type ())
GType              modelmux_rev_shared_get_type (void);
ModelMuxRevShared *modelmux_rev_shared_new (void);
ModelMuxRevShared *modelmux_rev_shared_ref (ModelMuxRevShared * rev);
void               modelmux_rev_shared_unref (ModelMuxRevShared * rev);
guint64            modelmux_rev_shared_get (ModelMuxRevShared * rev);
guint64            modelmux_rev_shared_bump (ModelMuxRevShared * rev);
 
typedef enum
{
  MODEL_INFER = 0,       
  MODEL_INFERSERVER,     
  MODEL_VISION_ENCODER,  
  MODEL_BACKEND_N        
} ModelType;
 
/* ================================================================== */
/* Backend registry                                                    */
/*                                                                     */
/* Every per-backend fact lives in ONE table (modelmux_backends[] in   */
/* gstnvmodelmux_config.c) and is reached through modelmux_backend().  */
/* Call sites ask a NAMED question -- "does this backend take a raw    */
/* .engine?" -- instead of testing the enum, so adding a backend is a  */
/* new row rather than a hunt for every `== MODEL_INFERSERVER` branch. */
/*                                                                     */
/* The enum is deliberately NOT a capability: nvinferserver refuses an */
/* engine because Triton owns its checkpoints, and a vision encoder    */
/* will refuse one for entirely different reasons. Two backends can    */
/* share an answer without sharing a reason, and a table records the   */
/* answer where a conditional records the coincidence.                 */
/* ================================================================== */
 
#define MM_BACKEND_AT_PGIE  (1u << 0)
#define MM_BACKEND_AT_SGIE  (1u << 1)
 
typedef struct
{
  const gchar *element;
  const gchar *const *markers;
  guint        positions;
  gboolean     engine_file;
  gboolean     version_artifact;
  gboolean     inplace_reload;
  gboolean     owns_placement;
  gboolean     multi_gpu_scale;
  gboolean     gpu_ids_list;
 
  const gchar *config_prop;
  const gchar *config_group;
  const gchar *engine_prop;
  gboolean     gie_id;
  const gchar *cfg_section;
  const gchar *gpu_key;
} ModelBackendInfo;
 
gboolean     modelmux_config_apply_properties (GstElement * element,
                                               const gchar * config_file,
                                               const gchar * group);
 
const ModelBackendInfo *modelmux_backend (ModelType type);
gboolean     modelmux_backend_at_position (ModelType type, gint process_mode);
 
typedef struct
{
  gchar    *name;          
  gchar    *config_file;   
  gchar    *engine_file;   
  gchar    *version;       
  guint     max_streams;   
  ModelType type;          
} ModelCatalogEntry;
 
typedef struct
{
  gchar    *name;          
  gchar    *version;       
  gchar    *engine;        
  gchar    *config;        
  gint      gpu;           
  gint      gie;           
  guint     batch;         
} ModelVersionArtifact;
 
typedef struct
{
  gchar    *sensor_id;        
  gchar    *primary;          
  gchar    *primary_version;  
  gchar    *shadow;           
  gchar    *shadow_version;   
} StreamModelBinding;
 
typedef struct
{
  guint     batch_size;
 
  /* defaults / behaviour */
  guint     per_model_max_streams; 
  gboolean  unified_batch;         
  gint      process_mode;          
  gboolean  gie_ids_from_config;
  gboolean  enable;                
  gboolean  shard_compact;         
  gboolean  compact_idle_models_across_pools; 
  gboolean  model_sharding;         
  /* [muxer]: nvstreammux settings shared by BOTH the per-model inference muxers (one per model
   * bin, batching that model's streams before nvinfer) AND the single outer combined mux
   * (ib->out_mux, merging all model bins' outputs downstream). width/height/live-source are
   * common to all muxers; only the flush cadence differs (per-model regroups an already-batched
   * upstream -> 10ms; combined aggregates across parallel inference -> ~33ms). The per-model
   * BATCH size is per_model_max_streams above; the combined-mux batch is auto-derived
   * (out_slots = unified ? per-model batch x2 : x1) and is NOT settable. */
  guint     mux_width;               
  guint     mux_height;              
  gboolean  mux_live_source;         
  guint     model_mux_push_timeout;  
  guint     combined_mux_push_timeout; 
  gboolean  attach_perf_metric;       
  guint     perf_metric_interval_sec; 
  gboolean  copy_primary_buffer;      
  gboolean  copy_shadow_buffer;       
  guint     copy_buffer_pool_size;    
  gboolean  lane_leaky;
 
  guint     gpu;
 
  gint      placement_policy;
 
  gboolean  auto_gpu_scale;
 
  ModelCatalogEntry     models[MM_MAX_MODELS];
  guint          num_models;
  ModelVersionArtifact versions[MM_MAX_MODELS * 4];
  guint          num_versions;
  GMutex         versions_lock;
  gchar         *default_primary;          
  gchar         *default_primary_version;  
  gchar         *default_shadow;           
  gchar         *default_shadow_version;   
  gint           default_primary_gpu;      
  gint           default_shadow_gpu;
 
  StreamModelBinding bindings[MM_MAX_STREAMS_DEFAULT];
  guint           num_bindings;
} ModelMuxConfig;
 
/* A/B provenance user-meta: InferenceProvenanceMeta is now PUBLIC, defined in
 * nvdsmeta_schema.h (tagged NVDS_CUSTOM_MSG_INFERENCE_PROVENANCE), so downstream
 * DS components can parse it without this private header. It is attached as
 * NvDsUserMeta on EACH frame before the combined display mux (ModelBin nvinfer
 * src for inferred frames, passthrough queue src for no-infer frames), and lets
 * nvmodelmux restore source_id after the combined mux rewrites it to a display
 * slot index. Flat struct => the copy func is a single memcpy that survives the
 * combined nvstreammux. */
 
typedef enum
{
  MODEL_WARMING = 0,     
  MODEL_WARMED,          
  MODEL_SERVING,         
  MODEL_FAILED           
} ModelStatus;
 
/* --------------------------------------------------------------------------------------- */
/* ModelBin: one logical model NAME for one ROLE.                                          */
/*                                                                                         */
/*   ghost sink_<idx>  ->  nvstreammux  ->  nvinfer  ->  nvstreamdemux  -> ghost src_<idx> */
/*                                                                                         */
/* Multiple streams share a single ModelBin (true batched inference). A recycled           */
/* index pool keeps mux/demux pad ids bounded (sink_0..sink_{max-1}).                      */
/*                                                                                         */
/* Lifecycle (role-agnostic): created at NULL (NOT_READY) -> loaded async to               */
/* READY (engine warmed) -> SERVING when streams attach -> back to READY when the          */
/* last stream leaves. The bin is only destroyed by an explicit unload.                    */
/* --------------------------------------------------------------------------------------- */
typedef struct
{
  gchar       *name;  
  gchar       *role;   
  ModelType   type;     
  gboolean     perf_on;
  ModelMuxPerf      *perf;
 
  gchar       *config_file;
  guint        unique_id;     
  guint        max_streams;
 
  guint        mux_width;
  guint        mux_height;
  guint        mux_push_timeout;
  gint         process_mode;  
  gboolean     mux_live_source;
  gint         mux_gpu;       
  GstElement  *bin;           
  GstElement  *mux;           
  GstElement  *conv_in;       
  GstElement  *infer;         
  GstElement  *conv_out;      
  GstElement  *demux;         
  GstPad      *zero_stream_drop_pad; 
  gulong       zero_stream_drop_probe; 
  GQueue      *free_idx;      
  GHashTable  *idx_to_stream; 
  gint        *slot_stream;   
  guint        num_streams;
  gboolean     served;        
  gint         status;        
  GThread     *load_thread;   
  const GHashTable *stream_names; 
  gpointer     pool;          
  gchar       *engine;        
  gchar       *version;       
  gchar       *key;           
  guint        inst;          
  gint         gpu;           
  gboolean     conv_cross;    
  gint         conv_gpu;      
  gint         cfg_gpu;       
  gboolean     pinned;        
  gpointer     next_shard;    
  GMutex       prov_lock;     
  gchar       *ota_old_version; 
  gchar       *ota_old_engine;
  gchar       *ota_old_config; 
  gchar       *ota_old_key;   
  gchar       *ota_new_key;
  gpointer     ota_ib;        
  gboolean     ota_await;     
  gpointer     ota_group;     
  gboolean     ota_ok;        
  gboolean     ota_compensating; 
  GPtrArray   *retired;       
} ModelBin;
 
typedef struct
{
  gchar    *name;             
  gchar    *version;          
  gint      gpu;              
  gchar    *key;              
  ModelBin *bin;              
} DefaultModelRef;
 
typedef struct
{
  gchar       *role;
  guint        base_uid;      
  guint        next_uid;      
  guint        max_streams;
  GstElement  *parent_pipeline;
  GstElement  *container;     
  GHashTable  *models;        
  const ModelMuxConfig *config; 
  const GHashTable *stream_names; 
  DefaultModelRef default_ref; 
  gpointer     owner;         
} ModelPool;
 
typedef enum
{
  PACK_PLACEMENT = 0,
  SPREAD_PLACEMENT
} ModelPlacementPolicy;
 
#define MM_GPU_ANY (-1)
 
/* ------------------------------------------------------------------  */
/* Per-stream ROUTING TABLE                                            */
/*                                                                     */
/* ModelMuxStreamEntry + ModelMuxRoleAttach are the bin's record of    */
/* WHAT IT HAS WIRED UP for every attached stream, so a later detach / */
/* model-routing / promote / compaction can find and unplug exactly the */
/* pads and elements that belong to that stream -- and nothing else.   */
/*                                                                     */
/*   ModelMuxBin.stream_wiring (hash: source_id -> ModelMuxStreamEntry*) */
/*     |                                                               */
/*     +-> StreamEntry { column, demux_src, tee,                       */
/*           prim: RoleAttach  -- lane to the PRIMARY model            */
/*           shad: RoleAttach  -- lane to the SHADOW  model (or off) } */
/*                                                                     */
/* ONE StreamEntry per attached stream; each embeds TWO RoleAttach     */
/* records inline (not allocated), one per role. A RoleAttach is the   */
/* wiring of ONE physical lane:                                        */
/*                                                                     */
/*   tee --> [conv] --> in_q --> ModelBin --> out_q --> out_mux        */
/*                                                                     */
/* i.e. WHICH model this role is routed to plus every element/pad the  */
/* lane occupies (tee src pad, queues, optional copy converter, the    */
/* combined-mux sink pad). Rerouting a role swaps only that lane's     */
/* model hookup; the queues, the other role and all other streams keep */
/* running. model/status and the MM_DEBUG routing dump are walks over  */
/* this table.                                                         */
/*                                                                     */
/* Lifetime: created by modelmux_bin_attach_stream, freed by           */
/* modelmux_stream_teardown on detach. All mutation happens on the main loop */
/* under ib->lock.                                                     */
/* ------------------------------------------------------------------ */
 
typedef struct
{
  gboolean     active;
  gboolean     busy;          
  gchar       *model;         
  ModelPool   *role;          
  GstElement  *conv;          
  GstElement  *in_q;          
  GstElement  *out_q;         
  GstPad      *tee_src;       
  GstPad      *out_mux_sink;  
  gint         out_idx;       
  GstPad      *tap_pad;       
  gulong       tap_probe_id;  
  GstPad      *verify_head_pad;   
  gulong       verify_head_probe_id;
  GstPad      *verify_queue_pad;  
  gulong       verify_queue_probe_id;
  gpointer     verify_ctx;    
  gboolean     passthru;      
  gchar       *pending_model; 
  gint         req_gpu;       
  gboolean     via_default;   
} ModelMuxRoleAttach;
 
typedef struct
{
  guint        stream_id;     
  gint         column;        
  guint        branch_serial; 
  GstPad      *demux_src;     
  GstPad      *branch_tap_pad; 
  gulong       branch_tap_probe_id;
  GstElement  *tee;           
  ModelMuxRoleAttach prim;
  ModelMuxRoleAttach shad;
  gpointer     promote_ctx;   
} ModelMuxStreamEntry;
 
/* --------------------------------------------------------------------  */
/* Frame accounting (MM_DEBUG only): per-(source,role) drop detection.   */
/*                                                                       */
/* Counts the SAME source frame at three points along its path so a      */
/* drop can be both DETECTED and LOCALIZED:                              */
/*   in       -- entered the bin              (in_demux probe)           */
/*   inferred -- passed the role's nvinfer    (provenance probe)         */
/*   delivered-- left the combined mux        (out-mux probe)            */
/* gap = in - delivered: steady = in-flight latency (OK); GROWING = a    */
/* real drop; <0 = make-before-break swap overlap. Counters are bumped   */
/* LOCK-FREE (g_atomic) on streaming threads; the *_base fields are set  */
/* on the main loop at role-attach / dump. Indexed by source_id (flat).  */
/* ------------------------------------------------------------------ */
#define MM_ACCT_MAX      256   
#define MM_ROLE_PRIMARY  0
#define MM_ROLE_SHADOW   1
#define MM_ROLE_SLOTS    2
 
typedef struct
{
  gint  in_base;      
  gint  infer_base;   
  gint  out_base;     
  gint  infer;        
  gint  out;          
  gint  last_out_fn;  
  gint  warm;         
  gint  floor;        
  gint  over;         
  gint  last_src_fn;  
} ModelMuxAcctRole;
 
typedef struct
{
  gint        in_count;          
  gint        last_in_fn;        
  ModelMuxAcctRole  role[MM_ROLE_SLOTS];
} ModelMuxAcct;
 
typedef struct
{
  guint   *src;               
  guint    n;
  gchar   *primary;           
  gchar   *shadow;            
  gboolean clear_shadow;      
  gint     p_gpu;             
  gint     s_gpu;
  gboolean p_via_default;     
  gboolean s_via_default;
} ModelMuxPendingRouteNote;
 
/* --------------------------------------------------------------------------- */
/* ModelMuxBin: the reusable inference subgraph.                               */
/*                                                                             */
/*   GhostPad sink (batched) -> nvstreamdemux -> per-stream tee                */
/*       -> { Primary ModelPool, Shadow ModelPool }                            */
/*   role outputs -> combined nvstreammux -> GhostPad src (one batched output) */
/*                                                                             */
/* The bin accepts ONE batched src (from nvmultiurisrcbin) on its sink GhostPad*/
/* and decouples it internally, so the bin's pad is its first/entry element.   */
/*                                                                             */
/* --------------------------------------------------------------------------- */
typedef struct
{
  GstElement *bin;           
  GstElement *parent_pipeline; 
  const ModelMuxConfig *config; 
  guint max_streams; 
  gboolean unified; 
  gint         active_streams; 
  GHashTable  *stream_names;  
  GHashTable  *stream_cam_ids;
  GHashTable  *stream_wiring; 
  GPtrArray   *retired_names; 
  GHashTable  *streams_pending; 
  GHashTable  *streams_cancelled; 
  GMutex       lock;          
  GMutex       free_lock;     
  gboolean     log_enabled;   
  guint        debug_interval; 
  GstPad      *sink_ghost;    
  GstElement  *in_demux;      
  GstElement  *out_mux;       
  GstPad      *src_ghost;     
  GQueue      *col_free_idx;  
  ModelPool   *primary_pool;
  ModelPool   *shadow_pool;
 
  /* Type-less model/load: a model loaded via the API has NO primary/shadow type.
   * It is warmed into this "limbo" map (role Unknown) inside the shared container,
   * and PROMOTED into primary/shadow on first use (stream-add or model/update) --
   * pure bookkeeping, zero-drop. Stays here (READY) until explicit model/unload.   */
  GHashTable  *limbo_models;  
  guint        next_limbo_gie;      
  gchar       *name_slot[MM_ACCT_MAX]; 
  GList       *pending_frees; 
  GList       *pending_sources; 
  guint        compact_poll_id; 
  guint        dump_source_id; 
  guint        perf_timer_id;   
  guint64      routing_revision; 
  ModelMuxRevShared *rev_shared; 
  GPtrArray   *pending_routes; 
  /* OTA rename-rollback hook (control layer): invoked on the MAIN loop by
   * modelmux_ota_rename_rollback_main AFTER a failed update's identity rename was
   * rolled back, with NO bin locks held at the call moment -- from_key = the
   * rejected update's key (rolled back FROM), to_key = the restored serving
   * key. Lets the owner re-sync its own key-addressed state. */
  void (*ota_rollback_cb) (gpointer owner, const gchar * from_key,
      const gchar * to_key);
  gpointer     ota_rollback_owner;
  gint         shutting_down;  
  gboolean     ever_attached; 
  gint         frame_count;   
  ModelMuxAcct       acct[MM_ACCT_MAX]; 
  /* attach-perf-metric: per-source THROUGHPUT (frames/sec leaving the bin) for
   * PASSTHROUGH streams -- which run no nvinfer, so they have no ModelMuxPerf bin
   * counter. Bin-lifetime (indexed by source_id, like acct[]) so the recording
   * probe never dangles. Single writer per source (one passthrough lane), so the
   * lock-free ModelMuxPerfCounter record is safe; ticked under ib->lock by the perf
   * timer; read by the perf table + model/status. No inference latency exists on
   * this path, so only the rate is meaningful. */
  ModelMuxPerfCounter thru_perf[MM_ACCT_MAX];
} ModelMuxBin;
 
/* ------------------------------------------------------------------ */
/* API                                                                */
/* ------------------------------------------------------------------ */
 
/* modelmux_config_parse takes the GObject element (GstNvModelMux) and is declared in
 * gstnvmodelmux.h -- it reconciles the parsed file with self->is_prop_set. */
void     modelmux_config_clear  (ModelMuxConfig * config);
/* Canonical model-instance key. model_key joins (name, version) into a freshly
 * allocated "name@version" (version defaults to MM_MODEL_VERSION_DEFAULT when NULL/empty);
 * used as the pool/limbo hash key so versions of one name coexist. model_key_split
 * splits a key back into bare name + version (both newly allocated; pass NULL to skip). */
gchar   *model_key (const gchar * name, const gchar * version);
void     model_key_split (const gchar * key, gchar ** name_out, gchar ** version_out);
/* TRUE iff `v` is a valid model version: a positive integer with no leading zero
 * ("1","2",...,"42"). Rejects NULL/empty, "0", "01", "1", "1.0", negatives, non-digits.
 * (Triton model-repository convention -- versions are numbered dirs.) */
gboolean modelmux_version_is_int (const gchar * v);
const ModelCatalogEntry *modelmux_config_find_model (const ModelMuxConfig * config, const gchar * name);
/* Auto-detect the inference backend from a model's config-file (nvinferserver protobuf
 * 'infer_config {' vs nvinfer INI '[property]'); defaults to nvinfer. modelmux_infer_plugin_str
 * returns the gst element name ("nvinfer" / "nvinferserver") for logs + element creation. */
ModelType  modelmux_detect_model_type (const gchar * config_file);
const gchar *modelmux_infer_plugin_str (ModelType type);
/* Derive a per-(name,version) config with this load's ARTIFACT + PLACEMENT applied:
 * `engine` (optional) swapped into the engine key and/or `gpu` (optional, -1 = keep the
 * config's device) written into the gpu key. Handles BOTH backends:
 *   nvinfer       : model-engine-file + gpu-id under [property] (INI) / property: (YAML)
 *   nvinferserver : gpu_ids: [N] inside infer_config (protobuf text or YAML). A raw
 *                   .engine does not map to Triton (its model repository owns the
 *                   checkpoints) -> warned + skipped; the gpu placement still applies.
 * Returns the derived config path (caller g_free), or NULL when nothing could be derived
 * (caller uses the base config as-is). The derived filename is tagged with BOTH
 * `model_name` and `version` (e.g. trafficcamnet_1_config_infer_primary.txt). */
gchar       *modelmux_config_derive (const gchar * base_cfg, const gchar * engine, gint gpu,
                                     gint gie,
                               const gchar * model_name, const gchar * version);
/* Record/refresh the per-version artifact + placement of a runtime model/load or
 * model/update, so later lazy warms, in-place updates and gpu-addressed routing resolve
 * this version's engine/config/device. gpu=-1 keeps any previously recorded placement. */
/* batch: 0 = leave the version's batch as-is (unset on a fresh entry). */
void         modelmux_config_register_version (ModelMuxConfig * config, const gchar * name,
                                         const gchar * version, const gchar * engine,
                                         const gchar * config_file, gint gpu, guint batch);
/* Placement of a loaded (name, version): the gpu recorded at load/update time, or -1
 * when the version runs on its config's device (gpu 0 unless the config overrides). */
/* Per-version batch (0 = unset; resolve name-level/catalog then global). Locked scan. */
guint        modelmux_config_version_batch (const ModelMuxConfig * config, const gchar * name,
                                          const gchar * version);
/* The per-VERSION gie-unique-id a [model-<name>-<version>] block declares (-1 = none). */
gint         modelmux_config_version_gie (const ModelMuxConfig * config, const gchar * name,
                                          const gchar * version);
gint         modelmux_config_version_gpu (const ModelMuxConfig * config, const gchar * name,
                                    const gchar * version);
/* TRUE when @name already has a version other than @version on record. The catalog base
 * config can back only ONE version; a sibling turns a bare load into two version numbers
 * resolving to one model. Locked scan. */
gboolean     modelmux_config_has_other_version (const ModelMuxConfig * config,
                                    const gchar * name, const gchar * version);
/* Resolve the EFFECTIVE config path for a (name, version) from its per-version artifact
 * ([model-<name>-<version>] block): a custom config and/or an engine swapped into it.
 * Returns a newly-allocated config path (caller g_free) when an override applies, or NULL
 * when the version has no override (caller uses the catalog base config as-is).
 * *derive_failed (optional) is set TRUE when the version DOES carry an explicit engine/gpu
 * override but deriving it FAILED -- the caller must then refuse to instantiate rather than
 * fall back to the base config (which would run the wrong artifact/device). */
gchar       *modelmux_config_resolve_version_cfg (const ModelMuxConfig * config, const gchar * name,
                                            const gchar * version,
                                            gboolean * derive_failed);
/* Device a model CONFIG FILE pins its inference to: nvinfer keyfile "gpu-id=N" or
 * nvinferserver pbtxt "gpu_ids: [N]". -1 = no key present (backend defaults to 0). */
gint         modelmux_config_file_gpu (const gchar * config_file);
gint         modelmux_config_file_process_mode (const gchar * config_file);
/* The gie-unique-id a model's infer config declares (-1 = absent). A stage adopts it
 * as the model's gie id so `operate-on-gie-id` stays config-knowable, exactly as with
 * a plain nvinfer; the SHADOW lane adds MM_SHADOW_GIE_OFFSET so an A/B pair stays
 * distinguishable in the object meta. */
gint         modelmux_config_file_gie_id (const gchar * config_file);
/* The gie-unique-id a SECONDARY operates ON (nvinfer `operate-on-gie-id`); -1 = absent,
 * nvinfer's default meaning every GIE. This is the model's INPUT filter, so it is also
 * the only correct answer to which stage's objects it actually classified -- the
 * MM_OVERLAY line uses it to label only the tiles the model really ran on. */
gint         modelmux_config_file_operate_on_gie (const gchar * config_file);
/* modelmux_gpu_stats (whole-device NVML stats) lives in gstnvmodelmux_perf.h -- the
 * module header its definition includes, so the prototype is visible there
 * (tmake builds with -Werror=missing-prototypes). Included above. */
/* Register a model at runtime (idempotent) so a stream can use a shadow/primary
 * that was not the configured default. Returns the (existing or new) entry. */
const ModelCatalogEntry *modelmux_config_register_model (ModelMuxConfig * config, const gchar * name,
                                            const gchar * config_file,
                                            const gchar * engine_file,
                                            const gchar * version,
                                            guint max_streams);
/* Update an ALREADY-registered model's artifacts in place (OTA): overwrites
 * config_file/engine_file/version when a non-NULL/non-empty value is supplied (others
 * left as-is). Returns the entry, or NULL if the name is not registered. */
const ModelCatalogEntry *modelmux_config_update_model (ModelMuxConfig * config, const gchar * name,
                                          const gchar * config_file,
                                          const gchar * engine_file,
                                          const gchar * version);
/* Resolve a stream's (primary, shadow) refs: config-time per-sensor binding
 * (matched by camera id) wins; any role it leaves unset falls back to that
 * role's RUNTIME default ref (the pool-embedded designation). Bindings are
 * static config; defaults are runtime state -- two sources, one resolution. */
void     modelmux_config_resolve_models (const ModelMuxConfig * config,
                                   const DefaultModelRef * def_primary,
                                   const DefaultModelRef * def_shadow,
                                   const gchar * camera_id,
                                   const gchar ** primary, const gchar ** shadow,
                                   const gchar ** primary_version,
                                   const gchar ** shadow_version,
                                   gboolean * primary_is_default,
                                   gboolean * shadow_is_default);
 
/* ModelBin */
ModelBin *model_bin_new (const gchar * name, const gchar * role,
                              const gchar * config_file, const gchar * engine_file,
                              const gchar * version, guint unique_id, guint max_streams,
                              const ModelMuxConfig * config,
                              GstElement * parent_pipeline, GstElement * container,
                              const GHashTable * stream_names, guint inst);
GstPad     *model_bin_attach (ModelBin * model_bin, guint stream_id);
gboolean    model_bin_detach (ModelBin * model_bin, guint stream_id);
gboolean    model_bin_has_capacity (ModelBin * model_bin);
guint       model_bin_num_streams (ModelBin * model_bin);
/* Warm the engine in the background so the bin reaches READY (idempotent). */
void        model_bin_load (ModelBin * model_bin);
ModelStatus model_bin_status (ModelBin * model_bin);
const gchar *model_status_str (ModelStatus s);
/* Borrowed model version identity used by provenance, diagnostics and status.
 * The returned pointer is owned by the model bin and remains valid for readers. */
G_GNUC_INTERNAL const gchar *model_version_str (ModelBin * model_bin);
/* Backend-aware engine/identity string captured from a warmed model bin.
 * Returns a newly-allocated string; caller frees. */
G_GNUC_INTERNAL gchar *get_infer_engine_str (ModelBin * model_bin);
void        model_bin_free (ModelBin * model_bin);
 
/* ModelPool */
ModelPool  *model_pool_new (const gchar * role, guint base_uid, guint max_streams,
                             GstElement * parent_pipeline, GstElement * container,
                             const ModelMuxConfig * config, const GHashTable * stream_names);
GstPad     *model_pool_attach (ModelPool * rb, guint stream_id,
             const gchar * model_name, gint gpu, GstPad * in_pad,
             guint branch_serial,
             GstElement ** in_q_out, GstElement ** out_q_out,
             GstElement ** conv_out, gboolean * cap_overflow,
             ModelBin ** attached_bin_out);
gboolean    model_pool_detach (ModelPool * rb, guint stream_id, const gchar * model_name);
/* Pre-create + warm a model in this pool so it is ready before streams arrive. */
/* batch: explicit per-instance cap (0 = resolve: version registry -> catalog -> global). */
gboolean    model_pool_load_model (ModelPool * rb, const gchar * model_name,
                                          const gchar * cfg_override, guint batch);
/* Explicit teardown of an IDLE (READY, 0-stream) model. Returns FALSE if it is
 * still serving streams. ModelBins are otherwise never destroyed on detach. */
gboolean    model_pool_unload_model (ModelPool * rb, const gchar * model_name);
void        model_pool_free (ModelPool * rb);
/* Internal read-only helper for status/perf reporting. Caller must already hold
 * the owning ModelMuxBin lock while traversing pool membership. */
G_GNUC_INTERNAL ModelBin *modelmux_perf_find_bin_for_source (ModelPool * pool,
                                                         guint source_id);
G_GNUC_INTERNAL void modelmux_role_set (ModelBin * model_bin, const gchar * role);
G_GNUC_INTERNAL const gchar *modelmux_role_get (ModelBin * model_bin);
G_GNUC_INTERNAL const gchar *modelmux_resolve_role (ModelBin * model_bin, guint source_id);
G_GNUC_INTERNAL gint modelmux_role_idx (const gchar * role);
G_GNUC_INTERNAL void modelmux_fmt_route_cell (gchar * buf, gsize n,
                                        const ModelMuxRoleAttach * ra);
G_GNUC_INTERNAL gboolean modelmux_debug_enabled (void);
G_GNUC_INTERNAL void modelmux_debug_configure (ModelMuxBin * ib);
G_GNUC_INTERNAL void modelmux_schedule_dump (ModelMuxBin * ib,
                                       guint delay_seconds);
 
/* ---- SECONDARY stage: linear chain -- ModelMuxSgieBin (gstnvmodelmux_sgie.c) ----
 * At process-mode=2 one model serves ALL streams on the already-batched buffer, so the
 * stage needs no demux/mux and no per-stream lanes -- only
 *   sink -> queue -> [xfer-in] -> infer -> [xfer-out] -> src.
 * Built instead of the ModelMuxBin when the stage is a secondary. */
typedef struct _ModelMuxSgieBin ModelMuxSgieBin;
 
ModelMuxSgieBin *modelmux_sgie_new (GstElement * parent, const gchar * name,
                                      const ModelMuxConfig * config);
void         modelmux_sgie_free (ModelMuxSgieBin * sgie_bin);
GstPad      *modelmux_sgie_get_sink (ModelMuxSgieBin * sgie_bin);
GstPad      *modelmux_sgie_get_src (ModelMuxSgieBin * sgie_bin);
/* the serving model's identity + element, for logging and model/status */
GstElement  *modelmux_sgie_get_infer (ModelMuxSgieBin * sgie_bin);
const gchar *modelmux_sgie_model_name (ModelMuxSgieBin * sgie_bin);
const gchar *modelmux_sgie_model_version (ModelMuxSgieBin * sgie_bin);
/* GET plane, answered by the stage that hosts the model. Same v1 shape as the
 * primary's, tagged with process_mode so the host can merge per-stage responses. */
gchar       *modelmux_sgie_status_json (ModelMuxSgieBin * sgie_bin,
                                        const gchar * f_model, const gchar * f_version);
gchar       *modelmux_sgie_route_json (ModelMuxSgieBin * sgie_bin);
/* Point this stage at the pipeline-wide routing counter (takes a ref). The
 * secondary has no routing table of its own, but a route APPLIED here still
 * invalidates every controller's if_revision, so it bumps the same number the
 * primary does -- see MODELMUX_CONTEXT_TYPE_ROUTING. */
void         modelmux_sgie_set_rev_shared (ModelMuxSgieBin * sgie_bin,
                                           ModelMuxRevShared * rev);
/* Bump it after a route this stage ACCEPTED (applied now, or parked on a warming
 * model -- the declarative intent is recorded either way, exactly as a queued
 * promotion counts at the primary). No-op when no counter is attached. */
void         modelmux_sgie_bump_routing_revision (ModelMuxSgieBin * sgie_bin);
/* Which line this stage owns in the MM_OVERLAY stack. The primary draws at the top and
 * each secondary gets its own line under it, so a pipeline with several secondaries
 * shows one name per stage instead of them fighting over one label. Assigned at
 * READY->PAUSED, when every stage's catalog is parsed and the set of stages is known. */
void         modelmux_sgie_set_overlay_slot (ModelMuxSgieBin * sgie_bin, guint slot);
/* Display facts for the MM_DEBUG models_table (see gstnvmodelmux_debug.c), one
 * resident model per @idx. Returns FALSE once @idx is past the last one, so the
 * caller walks with `for (i = 0; modelmux_sgie_get_info (bin, i, ...); i++)` and
 * never reaches into the struct itself. */
gboolean     modelmux_sgie_get_info (ModelMuxSgieBin * sgie_bin, guint idx,
                                     const gchar ** name, const gchar ** version,
                                     const gchar ** backend, guint * gie, gint * gpu,
                                     guint * streams, const gchar ** state,
                                     gboolean * serving, gchar ** engine);
/* model/update: in-place OTA on the stage's one inference element (nvinfer only).
 * Fills the verdict (@http/@err_code/@reason/@hint -- all static strings) whether it
 * triggers or refuses; returns TRUE only when the swap was handed to nvinfer, which
 * confirms it asynchronously. */
gboolean     modelmux_sgie_update (ModelMuxSgieBin * sgie_bin, const gchar * name,
                                   const gchar * from_version, const gchar * version,
                                   const gchar * config_file, const gchar * engine_file,
                                   gint * http, const gchar ** err_code,
                                   const gchar ** reason, const gchar ** hint);
/* model/load: build + warm ANOTHER version of a model this stage's catalog declares,
 * resident but NOT inferring -- "available, not active". It costs VRAM and changes no
 * output until an all-streams model/routing makes it the serving one. Same verdict
 * contract as _update; TRUE means accepted (202) and warming on its own thread. */
gboolean     modelmux_sgie_load (ModelMuxSgieBin * sgie_bin, const gchar * name,
                                 const gchar * version, const gchar * config_file,
                                 const gchar * engine_file, gint * http,
                                 const gchar ** err_code, const gchar ** reason,
                                 const gchar ** hint);
/* model/routing: make an already-resident model the SERVING one -- an all-streams
 * rebind, instant because the displaced model stays loaded and warm, and reversed by
 * the identical call naming the other version. A target still warming PARKS the route
 * (the current model keeps serving until it is ready) rather than being refused.
 * Payload shape -- streams:"all", no shadow, no camera list -- is the caller's to
 * check; this decides on residency. Same verdict contract as _load. */
gboolean     modelmux_sgie_route (ModelMuxSgieBin * sgie_bin, const gchar * name,
                                  const gchar * version, gint * http,
                                  const gchar ** err_code, const gchar ** reason,
                                  const gchar ** hint);
/* model/unload: release a RESIDENT model and its engine. Refuses exactly one thing --
 * the model that is SERVING, because a secondary cannot run without one; reroute to
 * another resident model first. An omitted @version is accepted only while the name has
 * a single version here. Same verdict contract as _load. */
gboolean     modelmux_sgie_unload (ModelMuxSgieBin * sgie_bin, const gchar * name,
                                   const gchar * version, gint * http,
                                   const gchar ** err_code, const gchar ** reason,
                                   const gchar ** hint);
 
/* Per-tile debug overlay (env MM_OVERLAY=1), shared by BOTH stages so one env var
 * governs the whole picture: the primary draws its provenance line at the top of each
 * tile, the secondary stacks the model it is serving just under it. Debug only.
 *
 * The two meta types are forward-declared rather than pulled in with nvdsmeta.h: this
 * header is included by every translation unit, and only the two overlay callers need
 * the full definitions (they include nvdsmeta.h themselves). */
struct _NvDsBatchMeta;
struct _NvDsFrameMeta;
gboolean     modelmux_overlay_enabled (void);
void         modelmux_draw_label (struct _NvDsBatchMeta * bmeta,
                                  struct _NvDsFrameMeta * fm,
                                  guint x_offset, guint y_offset, const gchar * text,
                                  const gchar * role);
 
/* ModelMuxBin */
ModelMuxBin *modelmux_bin_new (GstElement * pipeline, const gchar * name,
                                      guint max_streams, const ModelMuxConfig * config);
GstPad     *modelmux_bin_get_sink (ModelMuxBin * ib);
/* p_gpu/s_gpu: requested instance placement per role (MM_GPU_ANY = no constraint).
 * p_via_default/s_via_default: TRUE when that role's model came from the DEFAULT
 * fallback (see ModelMuxRoleAttach.via_default). */
/* name    = DISPLAY name (overlay, model/status) -- may be the camera_id when the
 *           host supplied only one identifier.
 * cam_id  = the ROUTABLE camera_id from stream/add, or NULL when none was given.
 *           Kept apart from `name` because only this one is accepted by
 *           POST /api/v1/model/routing (see ModelMuxBin.stream_cam_ids). */
gboolean    modelmux_bin_attach_stream (ModelMuxBin * ib, guint stream_id,
                                            const gchar * name, const gchar * cam_id,
                                            const gchar * primary, const gchar * shadow,
                                            gint p_gpu, gint s_gpu,
                                            gboolean p_via_default, gboolean s_via_default);
gboolean    modelmux_bin_detach_stream (ModelMuxBin * ib, guint stream_id);
/* Update the ROUTING TABLE for one stream: re-point its primary and/or shadow to
 * new model(s). Re-wires only the role(s) whose model changed, under a single
 * pad-block, leaving the unchanged role running. (Atomic per-stream model swap.)
 * p_gpu/s_gpu constrain WHICH instance serves each role (MM_GPU_ANY = any). */
gboolean    modelmux_bin_update_routing (ModelMuxBin * ib, guint stream_id,
                                             const gchar * primary, const gchar * shadow,
                                             gint p_gpu, gint s_gpu,
                                             gboolean p_via_default, gboolean s_via_default);
GstPad     *modelmux_bin_get_src (ModelMuxBin * ib);
/* number of streams currently attached (0 => the bin/sources have drained). */
guint       modelmux_bin_num_streams (ModelMuxBin * ib);
/* Pre-load the configured default primary (+ shadow if set) so they are READY
 * before any stream is added (zero attach-time downtime). */
/* Preload the configured default primary (+ shadow) so they are READY before any
 * stream attaches. wait=TRUE blocks until each default is WARMED and returns FALSE
 * if any FAILED to warm (caller fails the state change); wait=FALSE kicks the async
 * warm and returns TRUE immediately (legacy behaviour). */
gboolean    modelmux_bin_load_defaults (ModelMuxBin * ib);
/* TYPE-LESS model/load: warm the named model into the limbo map (role Unknown) so
 * it is READY but unassigned. Its primary/shadow type is decided LATER, on first
 * use (stream-add or model/update), which PROMOTES it into the matching pool. The
 * model must already be in the config registry (name/config-file). Idempotent.
 * `gpu` >= 0 PINS the bin to that device BEFORE the warm starts (conv-in placed
 * on the final device from the first buffer); -1 = the config's device. */
ModelStatus modelmux_bin_load_model (ModelMuxBin * ib, const gchar * key,
                                            const gchar * cfg_override, gint gpu,
                                            guint batch);
/* model/load with gpus[]: materialize ONE shard per listed GPU for (name,version) --
 * the base shard from cfgs[0]/gpus[0] plus n-1 PINNED sibling shards, each with its own
 * per-GPU derived config (cfgs[i]; NULL => the base config), all sharing one gie-id and
 * warming in the background like the base. n<=1 degrades to modelmux_bin_load_model
 * (identical single-instance path). ALL-OR-NOTHING: if any sibling shard fails to
 * materialize, every instance this call created (base included) is rolled back and
 * MODEL_FAILED is returned -- a partial group is never silently deployed. Otherwise
 * returns the base shard's status. */
ModelStatus modelmux_bin_load_model_instances (ModelMuxBin * ib,
                                            const gchar * key,
                                            const gchar * const cfgs[],
                                            const gint gpus[], guint n,
                                            guint batch);
/* TRUE iff `key` has a LIVE shard whose effective placement is `gpu` (a shard's own
 * recorded gpu, falling back to the version registry, then device 0). FALSE when the
 * model is not live -- callers fall back to the config registry. */
gboolean    modelmux_bin_model_on_gpu (ModelMuxBin * ib, const gchar * key,
                                            gint gpu);
/* Collect the DISTINCT effective gpus of `key`'s live shard chain into `out` (capacity
 * `cap`); returns the count (0 = not live). Used for engine-coverage validation and
 * teaching error messages. */
guint       modelmux_bin_model_gpus (ModelMuxBin * ib, const gchar * key,
                                            gint * out, guint cap);
/* LIVE instance's batch/stream cap for `key` (base shard's max_streams; 0 = not live).
 * Load/update admission uses it: a loaded version's batch is immutable. */
guint       modelmux_bin_model_batch (ModelMuxBin * ib, const gchar * key);
/* model/load with set_default_primary/shadow: create + warm the model DIRECTLY into the
 * role's pool (bypassing limbo), like a config-time default preload. cfg_override = the
 * per-version/engine-derived config (NULL => catalog base). Returns the model status. */
ModelStatus modelmux_bin_load_into_pool (ModelMuxBin * ib, gboolean shadow,
                                            const gchar * key, const gchar * cfg_override);
/* Re-designate the RUNTIME default for a role to (name, version[, gpu]). "Default" is derived
 * everywhere from the role pool's DefaultModelRef (routing fallback, unload protection, dump,
 * dedup), so this
 * single swap makes every subsystem follow; the prior default auto-demotes. `gpu` >= 0 persists
 * a placement pin for default-resolved streams; gpu < 0 keeps the existing pin when the NAME is
 * unchanged (OTA version rename) and resets it to MM_GPU_ANY on an identity change (a pin
 * belongs to the identity it was set for). Locks internally (callers must NOT hold ib->lock). */
void        modelmux_bin_set_default (ModelMuxBin * ib, gboolean shadow,
                                            const gchar * name, const gchar * version,
                                            gint gpu);
/* CLEAR a role's runtime default designation ("no default for this role"): the
 * counterpart of modelmux_bin_set_default, and what default{"shadow": null} needs.
 * Drops only the IDENTITY -- the model it named keeps serving its attached streams
 * and is reclaimed by the normal idle paths once they leave. Idempotent (clearing
 * an absent default is a no-op). Streams whose lane RESOLVED from this default are
 * not touched here: sweeping them is the caller's decision, exactly as it is for a
 * default switch. Locks internally; callers must NOT hold ib->lock. */
void        modelmux_bin_clear_default (ModelMuxBin * ib, gboolean shadow);
/* Apply a sensor id / display name to an ALREADY-ATTACHED stream (late bind).
 * Either field may be NULL to leave it unchanged; a stream that has gone is a no-op. */
void        modelmux_bin_set_stream_identity (ModelMuxBin * ib, guint stream_id,
                const gchar * name, const gchar * cam_id);
/* Read-only access to a role's runtime default designation (the pool-embedded
 * ref) for the element-side control plane (route guards, resolution). Returned
 * pointer is owned by the pool; main-loop readers are same-thread with all
 * writers, streaming-thread readers must hold ib->lock. */
const DefaultModelRef *modelmux_bin_get_default (ModelMuxBin * ib, gboolean shadow);
/* LOCKED "is this the configured default?" predicate, for callers that are NOT on
 * the main loop -- the REST control plane answers model/unload synchronously on the
 * civetweb thread. The DefaultModelRef strings are replaced+freed by the default
 * writers under ib->lock, so dereferencing the borrowed ref from
 * modelmux_bin_get_default() off the main loop races a writer freeing the old
 * key/name. This compares UNDER ib->lock and returns only a boolean, so no borrowed
 * pointer escapes to the caller.
 *   version != NULL/"" -> exact (name, version) IDENTITY match ("name@version")
 *   version == NULL/"" -> bare NAME match (ANY version of the name is a default)
 * Locks internally: callers must NOT already hold ib->lock. */
gboolean    modelmux_bin_is_configured_default (ModelMuxBin * ib, const gchar * name,
                const gchar * version);
/* Collect source-ids of streams currently routed to `key` in the given role (incl. a
 * passthrough stream awaiting promotion to it). Fills `out` (capacity `cap`), returns count.
 * Used to reroute streams off a demoted old default onto the new one. */
guint       modelmux_bin_streams_on_model (ModelMuxBin * ib, gboolean shadow,
                                            const gchar * key, guint * out, guint cap,
                                            gboolean default_only);
/* In-place OTA checkpoint reload: hot-swap the engine (and/or config) on the
 * already-loaded model `name` across ALL its shards -- same bin, same gie, no reroute.
 * `engine` set -> nvinfer "model-engine-file" (engine-only swap); else `config` -> full
 * "config-file-path" reload. `version` updates provenance/status. Returns TRUE if the
 * model was found and the reload was triggered; FALSE if `name` has no live bin. */
gboolean    modelmux_bin_reload_model (ModelMuxBin * ib, const gchar * name,
                                            const gchar * config, const gchar * engine,
                                            const gchar * version);
/* Multi-GPU in-place reload: like modelmux_bin_reload_model, but each shard is
 * swapped to the engine matching ITS effective gpu ({gpus[i] -> engines[i]}, n pairs).
 * ALL-OR-NOTHING admission under one lock hold: if any shard's gpu has no engine in
 * the map, NOTHING is swapped and FALSE is returned (caller reports GPU_ENGINE_MISSING). */
gboolean    modelmux_bin_reload_model_multi (ModelMuxBin * ib,
                                            const gchar * name, const gint gpus[],
                                            const gchar * const engines[], guint n,
                                            const gchar * version);
/* TRUE if `name` has a LIVE bin (limbo or either pool). Distinguishes a first-load
 * (create) from an OTA reload / update-on-missing. */
gboolean    modelmux_bin_model_loaded (ModelMuxBin * ib, const gchar * name);
/* TRUE while any live bin of bare model `name` has an OTA update awaiting nvinfer's
 * confirm (model/load admission gate: keeps the update's freed OLD key reservable
 * for a failed confirm's rename-back). */
gboolean    modelmux_bin_update_in_flight (ModelMuxBin * ib, const gchar * name);
/* Ensure the named model exists + is warming in the given role's pool (idempotent
 * get-or-create + background load). Promotes a limbo model into the role if needed.
 * Used by model/update; NOT called on stream-add. */
ModelStatus modelmux_bin_prepare_model (ModelMuxBin * ib,
                                               gboolean shadow, const gchar * name);
/* QUERY ONLY (no create, no load): current status of an ALREADY-loaded model in
 * the role's pool. Returns MODEL_WARMING/READY/SERVING, or -1 if the model
 * is absent (never loaded). Used by stream-add routing so a requested-but-not-
 * loaded model is NOT auto-loaded -- routing falls back to the default instead. */
gint        modelmux_bin_model_status (ModelMuxBin * ib,
                                            gboolean shadow, const gchar * name);
/* Explicit unload of a model in the given role's pool (model-unload API). Refuses
 * if the model is still SERVING; destroys the bin if READY. Returns TRUE
 * on success. */
/* JSON status dump; schema is always {"models":[...],"streams":[...]}. Filters are
 * INDEPENDENT -- each narrows its own array: f_model -> models[] = that model; f_stream/
 * f_sid (>=0) -> streams[] = that stream; both -> one model + one stream; none -> full.
 * An array whose filter is absent while the other's is present comes back []. g_free it. */
gchar      *modelmux_bin_status_json (ModelMuxBin * ib, const gchar * f_model,
                                           const gchar * f_version, const gchar * f_stream,
                                           gint f_sid);
/* Build the ROUTING-PLANE snapshot for GET /api/v1/model/routing: routes[] +
 * default{} + routing_revision, with streams GROUPED by identical routing state.
 * f_camera = optional strict point lookup on camera_id. NULL (and only NULL) is
 * the full snapshot; any non-NULL value -- INCLUDING "" -- is a PRESENT filter,
 * so an empty or unresolvable id yields an empty routes[] rather than the whole
 * fleet. Takes ib->lock itself.
 * Returns a newly allocated JSON string; caller frees with g_free. */
gchar      *modelmux_bin_route_json (ModelMuxBin * ib, const gchar * f_camera);
/* Bump the routing revision (under ib->lock): call after every APPLIED routing
 * change -- scoped reroute, default switch, in-place update trigger. */
void        modelmux_bin_bump_routing_revision (ModelMuxBin * ib);
/* Point this bin at the pipeline-wide counter (takes a ref, drops any previous).
 * Called by the element once the routing GstContext is negotiated; until then the
 * bin falls back to its own field, so the value is never garbage. */
void        modelmux_bin_set_rev_shared (ModelMuxBin * ib, ModelMuxRevShared * rev);
/* Current routing revision: the shared counter when one is attached, this bin's
 * own otherwise. Takes ib->lock. */
guint64     modelmux_bin_routing_revision (ModelMuxBin * ib);
/* REPLACE the mirrored list of accepted-but-deferred routes (under ib->lock),
 * taking ownership of `notes` and freeing whatever was there. notes==NULL clears
 * it. Wholesale replacement on purpose -- the control layer republishes its whole
 * queue after every change, so there is no per-entry sync to get wrong. */
void        modelmux_bin_set_pending_routes (ModelMuxBin * ib, GPtrArray * notes);
/* Free a ModelMuxPendingRouteNote (GDestroyNotify for the array above). */
void        modelmux_pending_route_note_free (gpointer note);
/* Sink-ghost query probe that answers /api/v1/model/status custom queries. */
G_GNUC_INTERNAL GstPadProbeReturn modelmux_status_query_probe (GstPad * pad,
                                                         GstPadProbeInfo * info,
                                                         gpointer udata);
/* Sink-ghost query probe that answers the SYNCHRONOUS control-admission query
 * (model/unload today): decides admission on the spot and writes back the
 * verdict + reason. udata is the ModelMuxBin (self = parent_pipeline). */
G_GNUC_INTERNAL GstPadProbeReturn modelmux_control_query_probe (GstPad * pad,
                                                         GstPadProbeInfo * info,
                                                         gpointer udata);
/* Post a model-plane COMPLETION event (model-loaded / -unloaded / -updated /
 * streams-routed) on the pipeline bus so apps react like they do for stream-add.
 * `src` is any element in the pipeline; the message routes up to the app bus. */
G_GNUC_INTERNAL void modelmux_post_model_event (GstElement * src,
                const gchar * event, const gchar * name, const gchar * version,
                gint gpu, gboolean ok, const gchar * detail);
/* Control-plane only: friendly source (camera) name for a source id, or NULL. */
G_GNUC_INTERNAL const gchar * modelmux_bin_source_name (ModelMuxBin * ib, guint sid);
/* Read-only: is (name@version)=`key` loaded (limbo/primary/shadow), and how many
 * streams is it serving across its shard chain? TRUE if present (*streams set).
 * *streams_csv (optional, owned) = the serving stream sensor names ("cam-1,cam-3").
 * Lets model/unload report a precise serving-vs-not-loaded reason up front. */
gboolean    modelmux_bin_key_serving (ModelMuxBin * ib, const gchar * key,
                guint * streams, gchar ** streams_csv);
/* Bare `name`: comma-separated sensor names of every stream serving ANY loaded
 * version of the name (owned; "" if none). For the name-only unload reason. */
gchar *     modelmux_bin_name_serving_streams (ModelMuxBin * ib, const gchar * name);
/* Scoped reroute -- n source ids, or n==0 => all active streams.
 * p_gpu/s_gpu: per-role placement constraint (MM_GPU_ANY = any). */
guint       modelmux_bin_update_routing_scoped (ModelMuxBin * ib, const guint * src_ids,
                                             guint n, const gchar * primary, const gchar * shadow,
                                             gint p_gpu, gint s_gpu,
                                             gboolean p_via_default, gboolean s_via_default);
/* Promote a stream's no-infer PASSTHROUGH primary to a now-WARMED model (deferred attach):
 * tears down the passthrough branch and attaches the model branch in its place. Called by
 * the control-plane poller once the model warms. No-op if the stream is gone / not passthru.
 * p_gpu/s_gpu: per-role placement constraint (MM_GPU_ANY = any). */
void        modelmux_bin_promote_passthru (ModelMuxBin * ib, guint stream_id,
                const gchar * model, const gchar * shadow, gint p_gpu, gint s_gpu,
                gboolean p_via_default, gboolean s_via_default);
/* Tag a passthrough stream with the model it is awaiting (deferred promotion), so the routing
 * table shows "<model> (passthru)" instead of "-". No-op if the stream isn't passthrough.
 * `gpu` records the requested placement the eventual promote must honour (MM_GPU_ANY = any). */
void        modelmux_bin_set_pending_model (ModelMuxBin * ib, guint stream_id,
                const gchar * model, gint gpu, gboolean via_default);
/* Clear an ABANDONED pending tag (deferred promote's target failed/unloaded): the
 * stream reverts to a plain passthrough (no intended model, no placement, no origin). */
void        modelmux_bin_clear_pending_model (ModelMuxBin * ib, guint stream_id);
/* List the streams (within the src_ids scope; n==0 => all active streams) whose PRIMARY is a
 * no-infer PASSTHROUGH branch. *out is allocated to the scope size (caller g_free's);
 * returns the count -- sized dynamically so a route-all can never silently truncate. Used by
 * model/routing: a passthrough stream can't be rerouted through the normal role machinery
 * (no model lane to swap) -- it must go through the deferred-PROMOTE path instead. */
guint       modelmux_bin_passthru_streams (ModelMuxBin * ib,
                const guint * src_ids, guint n, guint ** out);
/* Every wired stream's source_id (caller g_free's *out); returns the count.
 * Materialises a whole-pipeline scope into the fleet it means right now. */
guint       modelmux_bin_active_stream_ids (ModelMuxBin * ib, guint ** out);
/* IN-PLACE move: a promote (primary=<current shadow>, shadow="none") or a
 * clean swap (primary=<old shadow>, shadow=<old primary>) whose scope FULLY COVERS the
 * bins involved is done by re-labeling the existing bins (role+pool+records) instead of
 * building new ones -- no new bin, no engine reload, gie-id preserved, zero frame drop
 * (the bins' pads are never touched). Returns TRUE if handled in place; FALSE if not
 * eligible (caller falls back to the generic create+warm reroute). */
gboolean    modelmux_bin_try_inplace (ModelMuxBin * ib, const guint * src_ids,
                guint n, const gchar * primary, const gchar * shadow);
/* TYPE-LESS model/unload: free the model by name wherever it lives -- the limbo
 * map OR either pool -- when idle. No primary/shadow type needed. */
gboolean    modelmux_bin_unload_model (ModelMuxBin * ib, const gchar * key);
/* Result of a gpu-scoped model/unload (modelmux_bin_unload_model_gpus). */
typedef enum
{
  MM_UNLOAD_GPU_REMOVED = 0,  /* the requested per-gpu instance(s) were removed   */
  MM_UNLOAD_GPU_ALL,          /* the set covered every gpu -> whole version gone  */
  MM_UNLOAD_GPU_ABSENT,       /* (name@version) is not loaded                     */
  MM_UNLOAD_GPU_NO_MATCH,     /* loaded, but no instance sits on any listed gpu   */
  MM_UNLOAD_GPU_SERVING       /* a targeted instance is serving/mid-load: refused */
} ModelMuxUnloadGpuResult;
/* GPU-scoped model/unload: drain ONLY the instance(s) of `key` (name@version)
 * that sit on a gpu in gpus[0..n_gpus) -- the version's other per-gpu instances
 * keep serving. Idle-only per targeted instance (a SERVING/mid-load target
 * refuses the WHOLE op, changing nothing). If the set covers every gpu of the
 * version it degrades to a full unload (MM_UNLOAD_GPU_ALL). On SERVING refusal,
 * *serving_gpu / *serving_streams report the first offending instance so the
 * caller can emit a clear "still inferring" error. */
ModelMuxUnloadGpuResult modelmux_bin_unload_model_gpus (ModelMuxBin * ib,
                const gchar * key, const gint * gpus, guint n_gpus,
                gint * serving_gpu, guint * serving_streams, gchar ** serving_csv);
/* Unload EVERY non-serving version of `name` (bare): serving versions are left intact.
 * Returns the count unloaded; *present (optional) = how many "name@*" versions exist
 * (lets the caller tell "all serving" from "not loaded"). Used when no version given. */
guint       modelmux_bin_unload_versions (ModelMuxBin * ib, const gchar * name,
                guint * present);
void        modelmux_bin_free (ModelMuxBin * ib);
 
G_END_DECLS
 
#endif /* __DEEPSTREAM_MULTIMODEL_APP_H__ */