nv_core/
id.rs

1//! Strongly-typed identifiers for feeds, tracks, detections, and stages.
2//!
3//! All IDs are lightweight, `Copy`, and suitable for use as hash-map keys.
4
5use std::fmt;
6
7/// Unique identifier for a video feed within the runtime.
8///
9/// Backed by a `u64`. Two feeds in the same runtime always have distinct IDs.
10/// IDs are never reused within a single runtime session.
11#[derive(Clone, Copy, PartialEq, Eq, Hash)]
12pub struct FeedId(u64);
13
14impl FeedId {
15    /// Create a new `FeedId` from a raw value.
16    ///
17    /// Intended for internal use by the runtime. External callers should
18    /// receive `FeedId` values from [`FeedHandle`](crate) rather than constructing them.
19    #[must_use]
20    pub fn new(val: u64) -> Self {
21        Self(val)
22    }
23
24    /// Returns the underlying `u64` value.
25    #[must_use]
26    pub fn as_u64(self) -> u64 {
27        self.0
28    }
29}
30
31impl fmt::Display for FeedId {
32    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
33        write!(f, "feed-{}", self.0)
34    }
35}
36
37impl fmt::Debug for FeedId {
38    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39        write!(f, "FeedId({})", self.0)
40    }
41}
42
43/// Unique identifier for a tracked object across frames.
44///
45/// Backed by a `u64`. Track IDs are unique within a single feed session.
46/// After a feed restart, track IDs may be reused (the temporal store is cleared).
47#[derive(Clone, Copy, PartialEq, Eq, Hash)]
48pub struct TrackId(u64);
49
50impl TrackId {
51    /// Create a new `TrackId`.
52    #[must_use]
53    pub fn new(val: u64) -> Self {
54        Self(val)
55    }
56
57    /// Returns the underlying `u64` value.
58    #[must_use]
59    pub fn as_u64(self) -> u64 {
60        self.0
61    }
62}
63
64impl fmt::Display for TrackId {
65    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
66        write!(f, "track-{}", self.0)
67    }
68}
69
70impl fmt::Debug for TrackId {
71    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
72        write!(f, "TrackId({})", self.0)
73    }
74}
75
76/// Unique identifier for a single detection within a frame.
77///
78/// Backed by a `u64`. Detection IDs are unique within a single frame's
79/// [`DetectionSet`](crate).
80#[derive(Clone, Copy, PartialEq, Eq, Hash)]
81pub struct DetectionId(u64);
82
83impl DetectionId {
84    /// Create a new `DetectionId`.
85    #[must_use]
86    pub fn new(val: u64) -> Self {
87        Self(val)
88    }
89
90    /// Returns the underlying `u64` value.
91    #[must_use]
92    pub fn as_u64(self) -> u64 {
93        self.0
94    }
95}
96
97impl fmt::Display for DetectionId {
98    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99        write!(f, "det-{}", self.0)
100    }
101}
102
103impl fmt::Debug for DetectionId {
104    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
105        write!(f, "DetectionId({})", self.0)
106    }
107}
108
109/// Identifier for a perception stage.
110///
111/// A compile-time `&'static str` name, not a runtime-generated value.
112/// Stage names are fixed in the stage implementation (e.g., `"yolov8_detector"`).
113///
114/// `StageId` is `Copy` and zero-allocation.
115#[derive(Clone, Copy, PartialEq, Eq, Hash)]
116pub struct StageId(pub &'static str);
117
118impl StageId {
119    /// Returns the stage name as a string slice.
120    #[must_use]
121    pub fn as_str(self) -> &'static str {
122        self.0
123    }
124}
125
126impl fmt::Display for StageId {
127    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
128        f.write_str(self.0)
129    }
130}
131
132impl fmt::Debug for StageId {
133    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
134        write!(f, "StageId(\"{}\")", self.0)
135    }
136}
137
138#[cfg(test)]
139mod tests {
140    use super::*;
141
142    #[test]
143    fn feed_id_display() {
144        let id = FeedId::new(42);
145        assert_eq!(id.to_string(), "feed-42");
146    }
147
148    #[test]
149    fn stage_id_copy() {
150        let a = StageId("detector");
151        let b = a;
152        assert_eq!(a, b);
153    }
154
155    #[test]
156    fn ids_are_copy_and_eq() {
157        let t = TrackId::new(1);
158        let d = DetectionId::new(2);
159        assert_eq!(t, TrackId::new(1));
160        assert_eq!(d, DetectionId::new(2));
161    }
162}
nv_core/id.rs

nv_core/
id.rs
