fedimint_client/client/
handle.rs

Help
1use std::ops;
2use std::sync::Arc;
3use std::time::Duration;
4
5use anyhow::format_err;
6use fedimint_core::runtime;
7use fedimint_core::util::FmtCompactAnyhow as _;
8use fedimint_logging::LOG_CLIENT;
9#[cfg(not(target_family = "wasm"))]
10use tokio::runtime::{Handle as RuntimeHandle, RuntimeFlavor};
11use tracing::{debug, error, trace, warn};
12
13use super::Client;
14use crate::ClientBuilder;
15
16/// User handle to the [`Client`] instance
17///
18/// On the drop of [`ClientHandle`] the client will be shut-down, and resources
19/// it used freed.
20///
21/// Notably it [`ops::Deref`]s to the [`Client`] where most
22/// methods live.
23///
24/// Put this in an Arc to clone it (see [`ClientHandleArc`]).
25#[derive(Debug)]
26pub struct ClientHandle {
27    inner: Option<Arc<Client>>,
28}
29
30/// An alias for a reference counted [`ClientHandle`]
31pub type ClientHandleArc = Arc<ClientHandle>;
32
33impl ClientHandle {
34    /// Create
35    pub(crate) fn new(inner: Arc<Client>) -> Self {
36        ClientHandle {
37            inner: inner.into(),
38        }
39    }
40
41    pub(crate) fn as_inner(&self) -> &Arc<Client> {
42        self.inner.as_ref().expect("Inner always set")
43    }
44
45    pub fn start_executor(&self) {
46        self.as_inner().start_executor();
47    }
48
49    /// Shutdown the client.
50    pub async fn shutdown(mut self) {
51        self.shutdown_inner().await;
52    }
53
54    async fn shutdown_inner(&mut self) {
55        let Some(inner) = self.inner.take() else {
56            error!(
57                target: LOG_CLIENT,
58                "ClientHandleShared::shutdown called twice"
59            );
60            return;
61        };
62        inner.executor.stop_executor();
63        let db = inner.db.clone();
64        debug!(target: LOG_CLIENT, "Waiting for client task group to shut down");
65        if let Err(err) = inner
66            .task_group
67            .clone()
68            .shutdown_join_all(Some(Duration::from_secs(30)))
69            .await
70        {
71            warn!(target: LOG_CLIENT, err = %err.fmt_compact_anyhow(), "Error waiting for client task group to shut down");
72        }
73
74        let client_strong_count = Arc::strong_count(&inner);
75        debug!(target: LOG_CLIENT, "Dropping last handle to Client");
76        // We are sure that no background tasks are running in the client anymore, so we
77        // can drop the (usually) last inner reference.
78        drop(inner);
79
80        if client_strong_count != 1 {
81            debug!(target: LOG_CLIENT, count = client_strong_count - 1, LOG_CLIENT, "External Client references remaining after last handle dropped");
82        }
83
84        let db_strong_count = db.strong_count();
85        if db_strong_count != 1 {
86            debug!(target: LOG_CLIENT, count = db_strong_count - 1, "External DB references remaining after last handle dropped");
87        }
88        trace!(target: LOG_CLIENT, "Dropped last handle to Client");
89    }
90
91    /// Restart the client
92    ///
93    /// Returns false if there are other clones of [`ClientHandle`], or starting
94    /// the client again failed for some reason.
95    ///
96    /// Notably it will re-use the original [`fedimint_core::db::Database`]
97    /// handle, and not attempt to open it again.
98    pub async fn restart(self) -> anyhow::Result<ClientHandle> {
99        let (builder, config, api_secret, root_secret) = {
100            let client = self
101                .inner
102                .as_ref()
103                .ok_or_else(|| format_err!("Already stopped"))?;
104            let builder = ClientBuilder::from_existing(client);
105            let config = client.config().await;
106            let api_secret = client.api_secret.clone();
107            let root_secret = client.root_secret.clone();
108
109            (builder, config, api_secret, root_secret)
110        };
111        self.shutdown().await;
112
113        builder.build(root_secret, config, api_secret, false).await
114    }
115}
116
117impl ops::Deref for ClientHandle {
118    type Target = Client;
119
120    fn deref(&self) -> &Self::Target {
121        self.inner.as_ref().expect("Must have inner client set")
122    }
123}
124
125/// We need a separate drop implementation for `Client` that triggers
126/// `Executor::stop_executor` even though the `Drop` implementation of
127/// `ExecutorInner` should already take care of that. The reason is that as long
128/// as the executor task is active there may be a cycle in the
129/// `Arc<Client>`s such that at least one `Executor` never gets dropped.
130impl Drop for ClientHandle {
131    fn drop(&mut self) {
132        if self.inner.is_none() {
133            return;
134        }
135
136        // We can't use block_on in single-threaded mode or wasm
137        #[cfg(target_family = "wasm")]
138        let can_block = false;
139        #[cfg(not(target_family = "wasm"))]
140        // nosemgrep: ban-raw-block-on
141        let can_block = RuntimeHandle::current().runtime_flavor() != RuntimeFlavor::CurrentThread;
142        if !can_block {
143            let inner = self.inner.take().expect("Must have inner client set");
144            inner.executor.stop_executor();
145            if cfg!(target_family = "wasm") {
146                error!(target: LOG_CLIENT, "Automatic client shutdown is not possible on wasm, call ClientHandle::shutdown manually.");
147            } else {
148                error!(target: LOG_CLIENT, "Automatic client shutdown is not possible on current thread runtime, call ClientHandle::shutdown manually.");
149            }
150            return;
151        }
152
153        debug!(target: LOG_CLIENT, "Shutting down the Client on last handle drop");
154        #[cfg(not(target_family = "wasm"))]
155        runtime::block_in_place(|| {
156            runtime::block_on(self.shutdown_inner());
157        });
158    }
159}
fedimint_client/client/handle.rs

fedimint_client/client/
handle.rs
