leptos_use/
use_web_lock.rs

1use default_struct_builder::DefaultBuilder;
2use std::future::Future;
3use thiserror::Error;
4use wasm_bindgen::JsValue;
5pub use web_sys::LockMode;
6
7/// Rustified [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API).   
8///
9/// The **Web Locks API** allows scripts running in one tab or worker to asynchronously acquire a
10/// lock, hold it while work is performed, then release it. While held, no other script executing
11/// in the same origin can acquire the same lock, which allows a web app running in multiple tabs or
12/// workers to coordinate work and the use of resources.
13///
14/// > This function requires `--cfg=web_sys_unstable_apis` to be activated as
15/// > [described in the wasm-bindgen guide](https://rustwasm.github.io/docs/wasm-bindgen/web-sys/unstable-apis.html).
16///
17/// ## Demo
18///
19/// [Link to Demo](https://github.com/Synphonyte/leptos-use/tree/main/examples/use_web_lock)
20///
21/// ## Usage
22///
23/// ```
24/// # use leptos::prelude::*;
25/// # use leptos_use::use_web_lock;
26/// #
27/// async fn my_process(_lock: web_sys::Lock) -> i32 {
28///     // do sth
29///     42
30/// }
31///
32/// # #[component]
33/// # fn Demo() -> impl IntoView {
34/// leptos::task::spawn_local(async {
35///     let res = use_web_lock("my_lock", my_process).await;
36///     assert!(matches!(res, Ok(42)));
37/// });
38/// #
39/// # view! { }
40/// # }
41/// ```
42///
43/// ## Server-Side Rendering
44///
45/// On the server this returns `Err(UseWebLockError::Server)` and the task is not executed.
46// #[doc(cfg(feature = "use_web_lock"))]
47pub async fn use_web_lock<C, F, R>(name: &str, callback: C) -> Result<R, UseWebLockError>
48where
49    C: FnOnce(web_sys::Lock) -> F + 'static,
50    F: Future<Output = R>,
51    R: 'static,
52{
53    use_web_lock_with_options(name, callback, UseWebLockOptions::default()).await
54}
55
56/// Version of [`fn@crate::use_web_lock`] that takes a `UseWebLockOptions`. See [`fn@crate::use_web_lock`] for how to use.
57// #[doc(cfg(feature = "use_web_lock"))]
58pub async fn use_web_lock_with_options<C, F, R>(
59    name: &str,
60    callback: C,
61    options: UseWebLockOptions,
62) -> Result<R, UseWebLockError>
63where
64    C: FnOnce(web_sys::Lock) -> F + 'static,
65    F: Future<Output = R>,
66    R: 'static,
67{
68    #[cfg(feature = "ssr")]
69    {
70        let _ = name;
71        let _ = callback;
72        let _ = options;
73
74        Err(UseWebLockError::Server)
75    }
76
77    #[cfg(not(feature = "ssr"))]
78    {
79        use crate::js_fut;
80        use leptos::prelude::window;
81        use std::sync::{Arc, Mutex};
82        use wasm_bindgen::closure::Closure;
83        use wasm_bindgen::JsCast;
84        use wasm_bindgen_futures::future_to_promise;
85
86        let ret_value = Arc::new(Mutex::new(None));
87
88        let handler = Closure::once(Box::new({
89            let ret_value = Arc::clone(&ret_value);
90
91            move |lock| {
92                future_to_promise(async move {
93                    let ret = callback(lock).await;
94                    ret_value.lock().expect("Lock failed").replace(ret);
95                    Ok(JsValue::null())
96                })
97            }
98        }) as Box<dyn FnOnce(web_sys::Lock) -> _>)
99        .into_js_value();
100
101        let lock_promise = window()
102            .navigator()
103            .locks()
104            .request_with_options_and_callback(
105                name,
106                &options.to_web_sys(),
107                handler.unchecked_ref(),
108            );
109
110        js_fut!(lock_promise)
111            .await
112            .map(move |_| {
113                Arc::into_inner(ret_value)
114                    .expect("Arc has more than one reference still")
115                    .into_inner()
116                    .expect("Lock failed")
117                    .expect("Return value was None")
118            })
119            .map_err(UseWebLockError::Failed)
120    }
121}
122
123#[derive(Error, Debug)]
124pub enum UseWebLockError {
125    #[error("Lock cannot be acquired on the server")]
126    Server,
127
128    #[error("Lock failed")]
129    Failed(JsValue),
130}
131
132/// Options for [`fn@crate::use_web_lock_with_options`].
133// #[doc(cfg(feature = "use_web_lock"))]
134#[allow(dead_code)]
135#[derive(DefaultBuilder)]
136pub struct UseWebLockOptions {
137    /// The default mode is `LockMode::Exclusive`, but `LockMode::Shared` can be specified.
138    /// There can be only one `Exclusive` holder of a lock, but multiple `Shared` requests can be
139    /// granted at the same time. This can be used to implement the
140    /// [readers-writer pattern](https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock).
141    mode: LockMode,
142
143    /// If `true`, the lock request will fail if the lock cannot be granted immediately without
144    /// waiting. The callback is invoked with `null`. Defaults to `false`.
145    if_available: bool,
146
147    /// If `true`, then any held locks with the same name will be released, and the request will
148    /// be granted, preempting any queued requests for it. Defaults to `false`.
149    steal: bool,
150    // TODO : add abort signal (this also requires to create a wrapper for AbortSignal similar to UseWindow)
151}
152
153#[cfg(not(feature = "ssr"))]
154impl UseWebLockOptions {
155    fn to_web_sys(&self) -> web_sys::LockOptions {
156        let options = web_sys::LockOptions::new();
157        options.set_mode(self.mode);
158        options.set_if_available(self.if_available);
159        options.set_steal(self.steal);
160
161        options
162    }
163}
164
165impl Default for UseWebLockOptions {
166    fn default() -> Self {
167        Self {
168            mode: LockMode::Exclusive,
169            if_available: false,
170            steal: false,
171        }
172    }
173}
leptos_use/use_web_lock.rs

leptos_use/
use_web_lock.rs
