wasm_bindgen/cache/
intern.rs

1use cfg_if::cfg_if;
2
3cfg_if! {
4    if #[cfg(feature = "enable-interning")] {
5        use std::thread_local;
6        use std::string::String;
7        use std::borrow::ToOwned;
8        use std::cell::RefCell;
9        use std::collections::HashMap;
10        use crate::JsValue;
11
12        struct Cache {
13            entries: RefCell<HashMap<String, JsValue>>,
14        }
15
16        thread_local! {
17            static CACHE: Cache = Cache {
18                entries: RefCell::new(HashMap::new()),
19            };
20        }
21
22        /// This returns the raw index of the cached JsValue, so you must take care
23        /// so that you don't use it after it is freed.
24        pub(crate) fn unsafe_get_str(s: &str) -> Option<u32> {
25            CACHE.with(|cache| {
26                let cache = cache.entries.borrow();
27
28                cache.get(s).map(|x| x.idx)
29            })
30        }
31
32        fn intern_str(key: &str) {
33            CACHE.with(|cache| {
34                let entries = &cache.entries;
35
36                // Can't use `entry` because `entry` requires a `String`
37                if !entries.borrow().contains_key(key) {
38                    // Note: we must not hold the borrow while we create the `JsValue`,
39                    // because it will try to look up the value in the cache first.
40                    let value = JsValue::from(key);
41                    entries.borrow_mut().insert(key.to_owned(), value);
42                }
43            })
44        }
45
46        fn unintern_str(key: &str) {
47            CACHE.with(|cache| {
48                let mut cache = cache.entries.borrow_mut();
49
50                cache.remove(key);
51            })
52        }
53    }
54}
55
56/// Interns Rust strings so that it's much faster to send them to JS.
57///
58/// Sending strings from Rust to JS is slow, because it has to do a full `O(n)`
59/// copy and *also* encode from UTF-8 to UTF-16. This must be done every single
60/// time a string is sent to JS.
61///
62/// If you are sending the same string multiple times, you can call this `intern`
63/// function, which simply returns its argument unchanged:
64///
65/// ```rust
66/// # use wasm_bindgen::intern;
67/// intern("foo") // returns "foo"
68/// # ;
69/// ```
70///
71/// However, if you enable the `"enable-interning"` feature for wasm-bindgen,
72/// then it will add the string into an internal cache.
73///
74/// When you send that cached string to JS, it will look it up in the cache,
75/// which completely avoids the `O(n)` copy and encoding. This has a significant
76/// speed boost (as high as 783%)!
77///
78/// However, there is a small cost to this caching, so you shouldn't cache every
79/// string. Only cache strings which have a high likelihood of being sent
80/// to JS multiple times.
81///
82/// Also, keep in mind that this function is a *performance hint*: it's not
83/// *guaranteed* that the string will be cached, and the caching strategy
84/// might change at any time, so don't rely upon it.
85#[inline]
86pub fn intern(s: &str) -> &str {
87    #[cfg(feature = "enable-interning")]
88    intern_str(s);
89
90    s
91}
92
93/// Removes a Rust string from the intern cache.
94///
95/// This does the opposite of the [`intern`](fn.intern.html) function.
96///
97/// If the [`intern`](fn.intern.html) function is called again then it will re-intern the string.
98#[allow(unused_variables)]
99#[inline]
100pub fn unintern(s: &str) {
101    #[cfg(feature = "enable-interning")]
102    unintern_str(s);
103}
wasm_bindgen/cache/intern.rs

wasm_bindgen/cache/
intern.rs
