diff --git a/herodb/specs/backgroundinfo/sled.md b/herodb/specs/backgroundinfo/sled.md new file mode 100644 index 0000000..6ce0986 --- /dev/null +++ b/herodb/specs/backgroundinfo/sled.md @@ -0,0 +1,113 @@ +======================== +CODE SNIPPETS +======================== +TITLE: Basic Database Operations with sled in Rust +DESCRIPTION: This snippet demonstrates fundamental operations using the `sled` embedded database in Rust. It covers opening a database tree, inserting and retrieving key-value pairs, performing range queries, deleting entries, and executing an atomic compare-and-swap operation. It also shows how to flush changes to disk for durability. + +SOURCE: https://github.com/spacejam/sled/blob/main/README.md#_snippet_0 + +LANGUAGE: Rust +CODE: +``` +let tree = sled::open("/tmp/welcome-to-sled")?; + +// insert and get, similar to std's BTreeMap +let old_value = tree.insert("key", "value")?; + +assert_eq!( + tree.get(&"key")?, + Some(sled::IVec::from("value")), +); + +// range queries +for kv_result in tree.range("key_1".."key_9") {} + +// deletion +let old_value = tree.remove(&"key")?; + +// atomic compare and swap +tree.compare_and_swap( + "key", + Some("current_value"), + Some("new_value"), +)?; + +// block until all operations are stable on disk +// (flush_async also available to get a Future) +tree.flush()?; +``` + +---------------------------------------- + +TITLE: Subscribing to sled Events Asynchronously (Rust) +DESCRIPTION: This snippet demonstrates how to asynchronously subscribe to events on key prefixes in a `sled` database. It initializes a `sled` database, creates a `Subscriber` for all key prefixes, inserts a key-value pair to trigger an event, and then uses `extreme::run` to await and process incoming events. The `Subscriber` struct implements `Future>`, allowing it to be awaited in an async context. + +SOURCE: https://github.com/spacejam/sled/blob/main/README.md#_snippet_1 + +LANGUAGE: Rust +CODE: +``` +let sled = sled::open("my_db").unwrap(); + +let mut sub = sled.watch_prefix(""); + +sled.insert(b"a", b"a").unwrap(); + +extreme::run(async move { + while let Some(event) = (&mut sub).await { + println!("got event {:?}", event); + } +}); +``` + +---------------------------------------- + +TITLE: Iterating Subscriber Events with Async/Await in Rust +DESCRIPTION: This snippet demonstrates how to asynchronously iterate over events from a `Subscriber` instance in Rust. Since `Subscriber` now implements `Future`, it can be awaited in a loop to process incoming events, enabling efficient prefix watching. The loop continues as long as new events are available. + +SOURCE: https://github.com/spacejam/sled/blob/main/CHANGELOG.md#_snippet_0 + +LANGUAGE: Rust +CODE: +``` +while let Some(event) = (&mut subscriber).await {} +``` + +---------------------------------------- + +TITLE: Suppressing TSAN Race on Arc::drop in Rust +DESCRIPTION: This suppression addresses a false positive race detection by ThreadSanitizer in Rust's `Arc::drop` implementation. TSAN fails to correctly reason about the raw atomic `Acquire` fence used after the strong-count atomic subtraction with a `Release` fence in the `Drop` implementation, leading to an erroneous race report. + +SOURCE: https://github.com/spacejam/sled/blob/main/tsan_suppressions.txt#_snippet_0 + +LANGUAGE: TSAN Suppression +CODE: +``` +race:Arc*drop +``` + +---------------------------------------- + +TITLE: Suppressing TSAN Race on std::thread::local in Rust +DESCRIPTION: This suppression addresses ThreadSanitizer false positives when using Rust's `std::thread::local`. Similar to `lazy_static`, `std::thread::local` utilizes implicit barriers that TSAN fails to recognize, leading to incorrect race condition reports. + +SOURCE: https://github.com/spacejam/sled/blob/main/tsan_suppressions.txt#_snippet_2 + +LANGUAGE: TSAN Suppression +CODE: +``` +race:std::thread::local +``` + +---------------------------------------- + +TITLE: Suppressing TSAN Race on lazy_static in Rust +DESCRIPTION: This suppression targets ThreadSanitizer false positives related to the `lazy_static` crate in Rust. `lazy_static` relies on implicit memory barriers that TSAN does not correctly detect, causing it to report races where none exist. + +SOURCE: https://github.com/spacejam/sled/blob/main/tsan_suppressions.txt#_snippet_1 + +LANGUAGE: TSAN Suppression +CODE: +``` +race:lazy_static +``` \ No newline at end of file