Skip to main content

mnn_runtime/
runtime.rs

1//! Runtime factory and process-wide coordination.
2
3use std::{
4    path::Path,
5    sync::{Arc, Mutex},
6};
7
8use crate::{Error, ExecutionMode, Model, Result, RuntimeConfig};
9
10/// Shareable model factory and process-level MNN execution policy.
11#[derive(Debug, Clone)]
12pub struct Runtime {
13    pub(crate) inner: Arc<RuntimeInner>,
14}
15
16#[derive(Debug)]
17pub(crate) struct RuntimeInner {
18    pub(crate) config: RuntimeConfig,
19    pub(crate) execution_gate: Option<Arc<Mutex<()>>>,
20}
21
22impl Runtime {
23    /// Version reported by the linked native MNN library.
24    #[must_use]
25    pub fn native_version() -> String {
26        mnn_runtime_sys::version()
27    }
28
29    /// Create a runtime after validating its configuration and compiled backend.
30    ///
31    /// # Errors
32    ///
33    /// Returns an error if the thread count is invalid or the selected backend
34    /// was not compiled or registered by the linked MNN library.
35    pub fn new(config: RuntimeConfig) -> Result<Self> {
36        if config.threads == 0 || config.threads > 32 {
37            return Err(Error::InvalidConfig(
38                "thread count must be between 1 and 32".to_owned(),
39            ));
40        }
41        i32::try_from(config.threads)
42            .map_err(|_| Error::InvalidConfig("thread count does not fit in an i32".to_owned()))?;
43        if config.queue_capacity == 0 {
44            return Err(Error::InvalidConfig(
45                "queue capacity must be positive".to_owned(),
46            ));
47        }
48        super::model::gpu_mode(&config)?;
49        super::model::validate_backend(config.backend)?;
50
51        let execution_gate = match config.execution {
52            ExecutionMode::Serialized => Some(mnn_runtime_sys::execution_gate()),
53            ExecutionMode::Parallel => None,
54        };
55
56        Ok(Self {
57            inner: Arc::new(RuntimeInner {
58                config,
59                execution_gate,
60            }),
61        })
62    }
63
64    /// Create the default CPU runtime.
65    ///
66    /// # Errors
67    ///
68    /// Returns an error when the linked MNN library has no CPU backend.
69    pub fn cpu() -> Result<Self> {
70        Self::new(RuntimeConfig::default())
71    }
72
73    /// Runtime configuration used for newly loaded models.
74    #[must_use]
75    pub fn config(&self) -> &RuntimeConfig {
76        &self.inner.config
77    }
78
79    /// Load an MNN model file and start its dedicated worker.
80    ///
81    /// # Errors
82    ///
83    /// Returns an error if the file cannot be read or MNN cannot load it.
84    pub fn load_file(&self, path: impl AsRef<Path>) -> Result<Model> {
85        let path = path.as_ref();
86        let bytes = std::fs::read(path).map_err(|source| Error::ModelRead {
87            path: path.to_path_buf(),
88            source,
89        })?;
90        self.load_bytes(bytes)
91    }
92
93    /// Load an MNN model from owned bytes and start its dedicated worker.
94    ///
95    /// # Errors
96    ///
97    /// Returns an error if the model is empty, invalid, unsupported, or its
98    /// worker cannot be started.
99    pub fn load_bytes(&self, bytes: impl Into<Vec<u8>>) -> Result<Model> {
100        Model::spawn(bytes.into(), self.inner.clone())
101    }
102}
103
104impl Default for Runtime {
105    fn default() -> Self {
106        Self::cpu().expect("the default CPU runtime configuration is valid")
107    }
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113
114    #[test]
115    fn rejects_zero_threads() {
116        let error = Runtime::new(RuntimeConfig::new().with_threads(0))
117            .expect_err("zero threads must be rejected");
118        assert!(matches!(error, Error::InvalidConfig(_)));
119    }
120
121    #[test]
122    fn serialized_runtimes_share_one_gate() {
123        let first = Runtime::cpu().expect("valid runtime");
124        let second = Runtime::cpu().expect("valid runtime");
125        assert!(Arc::ptr_eq(
126            first
127                .inner
128                .execution_gate
129                .as_ref()
130                .expect("serialized gate"),
131            second
132                .inner
133                .execution_gate
134                .as_ref()
135                .expect("serialized gate")
136        ));
137    }
138
139    #[test]
140    fn linked_mnn_reports_a_version() {
141        assert!(!Runtime::native_version().is_empty());
142        assert_ne!(Runtime::native_version(), "unknown");
143    }
144}