Skip to main content

open_net/api/net_status/
net_status_client.rs

1use std::fmt;
2use std::sync::Arc;
3
4use crate::net_status::NetworkSnapshot;
5use crate::net_status::NetworkStatusContext;
6use crate::subscription::{CallbackContext, StateReceiver, Subscription};
7use crate::{LogType, Result};
8
9use crate::module::net_status::inner::facade::NetworkObservationOwner;
10
11/// An independent view of the engine's shared network monitor.
12/// Clones share this view's lifecycle; other named views remain independent.
13#[derive(Clone)]
14pub struct NetStatusClient {
15    inner: Arc<NetworkObservationOwner>,
16}
17
18impl NetStatusClient {
19    pub(crate) fn new(context: NetworkStatusContext) -> Result<Self> {
20        crate::log_s!(LogType::Engine; "NetStatusClient-new");
21        Ok(Self {
22            inner: NetworkObservationOwner::new(context)?,
23        })
24    }
25
26    /// Start monitoring and await the first coherent observation.
27    /// Repeated calls share the active monitor and its initialization result.
28    pub async fn start(&self) -> Result<NetworkSnapshot> {
29        crate::log_s!(LogType::Engine; "NetStatusClient-start");
30        self.inner.start().await
31    }
32
33    /// Stop monitoring while keeping subscriptions alive for a later restart.
34    pub async fn stop(&self) -> Result<()> {
35        crate::log_s!(LogType::Engine; "NetStatusClient-stop");
36        self.inner.request_stop()?;
37        self.inner.wait_cleanup().await
38    }
39
40    /// Permanently close monitoring and publish its final Closed snapshot.
41    pub async fn shutdown(&self) -> Result<()> {
42        crate::log_s!(LogType::Engine; "NetStatusClient-shutdown");
43        self.inner.request_close();
44        self.inner.wait_cleanup().await
45    }
46
47    /// Read the latest coherent snapshot, including an inactive or final state.
48    pub fn snapshot(&self) -> Result<NetworkSnapshot> {
49        self.inner.snapshot()
50    }
51
52    /// Subscribe to the current snapshot and later changes across stop/restart.
53    pub fn subscribe(&self) -> Result<StateReceiver<NetworkSnapshot>> {
54        self.inner.subscribe_terminal()
55    }
56
57    /// Observe the same snapshots as an asynchronous subscription on the shared
58    /// callback pool. Keep the returned owner alive while observing changes.
59    pub fn on_change<F>(&self, callback: F) -> Result<Subscription>
60    where
61        F: Fn(CallbackContext, Result<NetworkSnapshot>) + Send + Sync + 'static,
62    {
63        self.subscribe()?.into_callback(callback)
64    }
65
66    pub(crate) fn request_destroy(&self) {
67        self.inner.request_close();
68    }
69
70    pub(crate) async fn destroy(&self) -> Result<()> {
71        crate::log_s!(LogType::Engine; "NetStatusClient-destroy");
72        self.inner.request_close();
73        self.inner.wait_cleanup().await
74    }
75}
76
77impl fmt::Debug for NetStatusClient {
78    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
79        formatter
80            .debug_struct("NetStatusClient")
81            .finish_non_exhaustive()
82    }
83}