From 510ccfa1af1932c551a0c2dc4d4572ef03126ab0 Mon Sep 17 00:00:00 2001 From: 0x5t4l1n Date: Sun, 25 Oct 2026 01:25:04 +0530 Subject: [PATCH] docs(dynamic_allowlist): document merge, read, insert, remove, and shared The public methods merge, read, insert, remove, and shared lacked doc comments, while their neighbours (new, from_set, replace, mark_synced, is_synced, wait_synced) were all documented. The most important gap is merge: unlike replace it does not mark the allowlist as synced, which is a subtle invariant that callers must observe to avoid wait_synced timing out forever. The new doc comment calls this out explicitly and refers to mark_synced so readers know what to call after consuming the authoritative source. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .../src/dynamic_string_allowlist.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/crates/openshell-core/src/dynamic_string_allowlist.rs b/crates/openshell-core/src/dynamic_string_allowlist.rs index 28ae389bea..526d77a359 100644 --- a/crates/openshell-core/src/dynamic_string_allowlist.rs +++ b/crates/openshell-core/src/dynamic_string_allowlist.rs @@ -78,27 +78,42 @@ impl DynamicStringAllowlist { .is_ok_and(|result| result.is_ok()) } + /// Add entries from `additional` into the allowlist without replacing the + /// existing set. + /// + /// Unlike [`Self::replace`], `merge` does **not** mark the allowlist as + /// synced. Call [`Self::mark_synced`] explicitly once the authoritative + /// source has been fully consumed, so that [`Self::wait_synced`] and + /// [`Self::is_synced`] report the correct state. pub fn merge(&self, additional: &BTreeSet) { self.write_guard().extend(additional.iter().cloned()); } + /// Read the current set. The returned guard holds a shared lock; drop it + /// promptly to avoid blocking writers. pub fn read(&self) -> std::sync::RwLockReadGuard<'_, BTreeSet> { self.read_guard() } + /// Return `true` if `namespace` is present in the allowlist. #[must_use] pub fn contains(&self, namespace: &str) -> bool { self.read_guard().contains(namespace) } + /// Insert a single entry. Returns `true` if the entry was not already + /// present. Does **not** mark the allowlist as synced. pub fn insert(&self, name: String) -> bool { self.write_guard().insert(name) } + /// Remove a single entry. Returns `true` if the entry was present. pub fn remove(&self, name: &str) -> bool { self.write_guard().remove(name) } + /// Return a cheap clone of the underlying `Arc>` for callers + /// that need direct access to the inner set. #[must_use] pub fn shared(&self) -> Arc>> { Arc::clone(&self.inner)