[−][src]Crate thread_scoped_ref
Thread scoped reference
A library that is similar to a thread local storage but allows to store references / dyn Trait within a scope.
It's similar to std::thread_local
but allows you to store non-static references. Since the
reference is non-static, the value has to be scoped (the reference MUST NOT escape the scope).
It also works with dynamic dispatch (e.g. dyn Trait
). Scopes can be nested. Everything is
thread-local.
Example
Short example:
use thread_scoped_ref::{thread_scoped_ref, scoped, with}; use std::collections::HashMap; thread_scoped_ref!(SOME_ENV_VALUES, HashMap<String, String>); /// It's not possible to pass `&HashMap<String, String>` to this function since it's called /// by some library you don't control... fn read_env_value() { // ... so we read from the static 'SOME_ENV_VALUES'. with(&SOME_ENV_VALUES, |maybe_env_values| { // don't "unwrap" in reality: Since `maybe_env_values` will be `None` if not // called within a scope! let env_values = maybe_env_values.unwrap(); assert_eq!("true", env_values.get("delete_entire_ssd").unwrap()); }); } /// An external library you don't control or generated code. fn external_library(function_ptr : fn()) { function_ptr(); } let mut env_values = HashMap::default(); env_values.insert("delete_entire_ssd".to_string(), "true".to_string()); // Create a scope. Note: We only need a reference to `env_values` (no move required). scoped(&SOME_ENV_VALUES, &env_values, || { external_library(read_env_value); });
Long example:
use thread_scoped_ref::{thread_scoped_ref, scoped, with}; /// Declare the `REF_TO_A_STRING`. thread_scoped_ref!(REF_TO_A_STRING, str); /// This function reads the value and prints the value. fn value_consumer() { with(&REF_TO_A_STRING, |maybe_string| { // `maybe_string` is `Some` if this is called within a scope, or `None` if not called // within a scope. if let Some(string) = maybe_string { println!("String is: '{}'", string); } else { println!("There's no string."); } }); } // Example #1: prints `There's no string` (since not called within a scope). value_consumer(); // Example #2: With a scope. let my_string = "The String!".to_string(); // note: We use the reference and not the actual string. It's not static! let my_string_ref = &my_string; scoped(&REF_TO_A_STRING, my_string_ref, || { // prints `String is: 'The String!'` value_consumer(); }); // Example #3: Nested scopes. let another_string = "Another string".to_string(); scoped(&REF_TO_A_STRING, &another_string, || { // prints `String is: 'Another string'` value_consumer(); // a nested scope. scoped(&REF_TO_A_STRING, my_string_ref, || { // prints `String is: 'The String!'` value_consumer(); }); // prints `String is: 'Another string'` value_consumer(); }); // Example #4: No scope (like example 1). prints `There's no string`. value_consumer();
Use case
It's useful if you need to 'inject' some sort of context into a function you provide that gets called by a library you don't control. One example is Serde: You can write custom serialize/deserialize methods but it's not possible to call them with custom data (a context) - unless you also write the serialization/deserialization of the container manually (not by using Serde derive).
Something like this can be achieved with thread scoped references. See the Serde demo test for details.
Macros
thread_scoped_ref | A shortcut macro for |
Structs
Scope | A scope. There's usually one scope per thread. |
Functions
scoped | Execute a function scoped with given value reference. |
with | Gets the reference to value from the current scope. Given function will receive
|