...

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<Output=Option<Event>>`, 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
+```