Skip to content

armgit / zed

Public Imported from GitHub
0

Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.

watch: Add snapshot-based channels (#63964)

Lukas Wirthf9a1fc898bae
diff --git a/Cargo.lock b/Cargo.lock
index 38da980bb1b..b11b119e4fd 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -20577,6 +20577,7 @@ dependencies = [
name = "watch"
version = "0.1.0"
dependencies = [
+ "arc-swap",
"ctor",
"futures 0.3.32",
"gpui",
diff --git a/Cargo.toml b/Cargo.toml
index c1c4824cb52..a7da1f80ef1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -523,6 +523,7 @@ aho-corasick = "1.1"
alacritty_terminal = { git = "https://github.com/zed-industries/alacritty", rev = "4c129667ce56611becdc82de6e28218c80e2e88f" }
any_vec = "0.14"
anyhow = "1.0.86"
+arc-swap = "1.9.0"
ashpd = { version = "0.13", default-features = false, features = [
"async-io",
"inhibit",
diff --git a/crates/watch/Cargo.toml b/crates/watch/Cargo.toml
index aea8b0bbbda..273a8b53c58 100644
--- a/crates/watch/Cargo.toml
+++ b/crates/watch/Cargo.toml
@@ -13,10 +13,11 @@ path = "src/watch.rs"
doctest = true
[dependencies]
+arc-swap.workspace = true
+futures.workspace = true
parking_lot.workspace = true
[dev-dependencies]
ctor.workspace = true
-futures.workspace = true
gpui = { workspace = true, features = ["test-support"] }
zlog.workspace = true
diff --git a/crates/watch/src/snapshot.rs b/crates/watch/src/snapshot.rs
new file mode 100644
index 00000000000..0b1c4066778
--- /dev/null
+++ b/crates/watch/src/snapshot.rs
@@ -0,0 +1,240 @@
+//! Provides a latest-value channel with independently owned snapshots.
+//!
+//! Channel synchronization uses atomic publication rather than reader/writer
+//! locks. Retaining a snapshot never prevents publication.
+//!
+//! ```
+//! let (mut sender, mut receiver) = watch::snapshot::channel(1);
+//! let previous = receiver.snapshot();
+//! assert_eq!(sender.send(2), Ok(()));
+//! assert_eq!(*previous, 1);
+//! assert_eq!(*receiver.snapshot(), 2);
+//! ```
+
+use crate::{NoReceiverError, NoSenderError};
+use arc_swap::ArcSwap;
+use futures::task::AtomicWaker;
+use std::{
+ ops,
+ pin::Pin,
+ sync::{
+ Arc, Weak,
+ atomic::{AtomicBool, Ordering::SeqCst},
+ },
+ task::{Context, Poll},
+};
+
+struct Versioned<T> {
+ value: T,
+ version: usize,
+}
+
+struct State<T> {
+ latest: ArcSwap<Versioned<T>>,
+ receivers: ArcSwap<Vec<Weak<AtomicWaker>>>,
+ closed: AtomicBool,
+}
+
+impl<T> State<T> {
+ fn subscribe(self: &Arc<Self>, version: usize) -> Receiver<T> {
+ let waker = Arc::new(AtomicWaker::new());
+ self.receivers.rcu(|receivers| {
+ let mut receivers = receivers.as_ref().clone();
+ receivers.push(Arc::downgrade(&waker));
+ receivers
+ });
+ Receiver {
+ state: self.clone(),
+ waker,
+ version,
+ }
+ }
+
+ fn wake_receivers(&self) -> Result<(), NoReceiverError> {
+ let mut result = Err(NoReceiverError);
+ for receiver in self.receivers.load().iter() {
+ if let Some(waker) = receiver.upgrade() {
+ result = Ok(());
+ waker.wake();
+ }
+ }
+ result
+ }
+}
+
+/// Creates a channel whose initial value is already considered seen.
+///
+/// Use [`Receiver::snapshot`] to read the initial value. Each send counts as a
+/// change, even when the value is equal; slow receivers skip intermediate values.
+pub fn channel<T>(value: T) -> (Sender<T>, Receiver<T>) {
+ let receiver = Receiver::constant(value);
+ let sender = Sender {
+ state: receiver.state.clone(),
+ };
+ (sender, receiver)
+}
+
+/// Publishes values to all receivers without waiting for snapshots to be released.
+pub struct Sender<T> {
+ state: Arc<State<T>>,
+}
+
+impl<T> Sender<T> {
+ /// Creates a receiver with the current version already considered seen.
+ pub fn receiver(&self) -> Receiver<T> {
+ let version = self.state.latest.load().version;
+ self.state.subscribe(version)
+ }
+
+ /// Replaces the latest value and wakes receivers.
+ ///
+ /// # Errors
+ ///
+ /// Returns [`NoReceiverError`] if no receivers remain. The value is still
+ /// stored and can be read by a subsequently created receiver.
+ pub fn send(&mut self, value: T) -> Result<(), NoReceiverError> {
+ let version = self.state.latest.load().version.wrapping_add(1);
+ self.state
+ .latest
+ .store(Arc::new(Versioned { value, version }));
+ self.state.wake_receivers()
+ }
+}
+
+impl<T> Drop for Sender<T> {
+ fn drop(&mut self) {
+ self.state.closed.store(true, SeqCst);
+ match self.state.wake_receivers() {
+ Ok(()) | Err(NoReceiverError) => {}
+ }
+ }
+}
+
+/// Observes publications independently of other receivers.
+///
+/// Cloning copies the last-seen version but creates an independent wake
+/// registration. A snapshot does not require the value to implement `Clone`.
+pub struct Receiver<T> {
+ state: Arc<State<T>>,
+ waker: Arc<AtomicWaker>,
+ version: usize,
+}
+
+impl<T> Clone for Receiver<T> {
+ fn clone(&self) -> Self {
+ self.state.subscribe(self.version)
+ }
+}
+
+impl<T> Drop for Receiver<T> {
+ fn drop(&mut self) {
+ let waker = Arc::downgrade(&self.waker);
+ self.state.receivers.rcu(|receivers| {
+ receivers
+ .iter()
+ .filter(|receiver| !receiver.ptr_eq(&waker))
+ .cloned()
+ .collect::<Vec<_>>()
+ });
+ }
+}
+
+impl<T> Receiver<T> {
+ /// Returns an owned snapshot and marks its version as seen.
+ ///
+ /// The snapshot remains valid after further sends or after the channel is
+ /// dropped, and does not prevent either operation.
+ pub fn snapshot(&mut self) -> Snapshot<T> {
+ let snapshot = self.state.latest.load_full();
+ self.version = snapshot.version;
+ Snapshot(snapshot)
+ }
+
+ /// Waits for an unseen publication and marks that version as seen.
+ ///
+ /// Dropping a pending future unregisters its waker without marking any
+ /// publication as seen.
+ ///
+ /// # Errors
+ ///
+ /// Returns [`NoSenderError`] after the sender is dropped and the final
+ /// publication has been seen.
+ pub fn changed(&mut self) -> impl Future<Output = Result<(), NoSenderError>> {
+ Changed { receiver: self }
+ }
+
+ /// Creates a fixed-value receiver whose change futures remain pending forever.
+ pub fn constant(value: T) -> Self {
+ Arc::new(State {
+ latest: ArcSwap::from_pointee(Versioned { value, version: 0 }),
+ receivers: ArcSwap::from_pointee(Vec::new()),
+ closed: AtomicBool::new(false),
+ })
+ .subscribe(0)
+ }
+}
+
+impl<T: Clone> Receiver<T> {
+ /// Waits for an unseen publication and clones the latest value.
+ ///
+ /// # Errors
+ ///
+ /// Returns [`NoSenderError`] after the sender is dropped and the final
+ /// publication has been seen.
+ pub async fn recv(&mut self) -> Result<T, NoSenderError> {
+ self.changed().await?;
+ Ok((*self.snapshot()).clone())
+ }
+}
+
+/// Owns an immutable channel value independently of its receiver.
+pub struct Snapshot<T>(Arc<Versioned<T>>);
+
+impl<T> Clone for Snapshot<T> {
+ fn clone(&self) -> Self {
+ Self(self.0.clone())
+ }
+}
+
+impl<T> ops::Deref for Snapshot<T> {
+ type Target = T;
+
+ fn deref(&self) -> &Self::Target {
+ &self.0.value
+ }
+}
+
+struct Changed<'a, T> {
+ receiver: &'a mut Receiver<T>,
+}
+
+impl<T> Future for Changed<'_, T> {
+ type Output = Result<(), NoSenderError>;
+
+ fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+ let receiver = &mut self.get_mut().receiver;
+ // Register before checking so a racing publication cannot go unnoticed.
+ receiver.waker.register(cx.waker());
+ // Observing closure must precede loading the value, so closure cannot
+ // hide a final publication that raced with this poll.
+ let closed = receiver.state.closed.load(SeqCst);
+ let snapshot = receiver.state.latest.load();
+ if snapshot.version != receiver.version {
+ receiver.version = snapshot.version;
+ Poll::Ready(Ok(()))
+ } else if closed {
+ Poll::Ready(Err(NoSenderError))
+ } else {
+ Poll::Pending
+ }
+ }
+}
+
+impl<T> Drop for Changed<'_, T> {
+ fn drop(&mut self) {
+ self.receiver.waker.take();
+ }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/crates/watch/src/snapshot/tests.rs b/crates/watch/src/snapshot/tests.rs
new file mode 100644
index 00000000000..2570e7d6236
--- /dev/null
+++ b/crates/watch/src/snapshot/tests.rs
@@ -0,0 +1,346 @@
+use super::*;
+use futures::task::{ArcWake, waker};
+use std::{
+ future::Future,
+ sync::{
+ Arc, Barrier,
+ atomic::{AtomicUsize, Ordering},
+ mpsc,
+ },
+ task::{Context, Poll, Waker},
+ thread,
+ time::Duration,
+};
+
+#[derive(Default)]
+struct WakeCounter(AtomicUsize);
+
+impl ArcWake for WakeCounter {
+ fn wake_by_ref(counter: &Arc<Self>) {
+ counter.0.fetch_add(1, Ordering::SeqCst);
+ }
+}
+
+fn counting_waker() -> (Waker, Arc<WakeCounter>) {
+ let counter = Arc::new(WakeCounter::default());
+ (waker(counter.clone()), counter)
+}
+
+fn poll_changed<T>(receiver: &mut Receiver<T>, waker: &Waker) -> Poll<Result<(), NoSenderError>> {
+ let mut changed = Box::pin(receiver.changed());
+ changed.as_mut().poll(&mut Context::from_waker(waker))
+}
+
+#[test]
+fn coalesces_publications_to_the_latest_snapshot() {
+ let (mut sender, mut receiver) = channel(0);
+ let (waker, _) = counting_waker();
+
+ assert_eq!(sender.send(1), Ok(()));
+ assert_eq!(sender.send(2), Ok(()));
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Ready(Ok(())));
+ assert_eq!(*receiver.snapshot(), 2);
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+}
+
+#[test]
+fn equal_values_are_distinct_publications() {
+ let (mut sender, mut receiver) = channel(7);
+ let (waker, _) = counting_waker();
+
+ assert_eq!(sender.send(7), Ok(()));
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Ready(Ok(())));
+ assert_eq!(sender.send(7), Ok(()));
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Ready(Ok(())));
+}
+
+#[test]
+fn initial_value_is_seen() {
+ let (_sender, mut receiver) = channel(3);
+ let (waker, _) = counting_waker();
+
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+ assert_eq!(*receiver.snapshot(), 3);
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+}
+
+#[test]
+fn snapshot_marks_the_latest_publication_as_seen() {
+ let (mut sender, mut receiver) = channel(0);
+ let (waker, _) = counting_waker();
+ assert_eq!(sender.send(1), Ok(()));
+ assert_eq!(*receiver.snapshot(), 1);
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+ drop(sender);
+ assert_eq!(
+ poll_changed(&mut receiver, &waker),
+ Poll::Ready(Err(NoSenderError))
+ );
+}
+
+#[test]
+fn clone_copies_seen_version_but_fresh_receiver_sees_current_version() {
+ let (mut sender, mut receiver) = channel(0);
+ assert_eq!(sender.send(1), Ok(()));
+ let mut clone = receiver.clone();
+ let mut fresh = sender.receiver();
+ let (waker, _) = counting_waker();
+
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Ready(Ok(())));
+ assert_eq!(poll_changed(&mut clone, &waker), Poll::Ready(Ok(())));
+ assert_eq!(poll_changed(&mut fresh, &waker), Poll::Pending);
+}
+
+#[test]
+fn retained_snapshots_do_not_require_clone_or_block_publication() {
+ #[derive(Debug, Eq, PartialEq)]
+ struct NotClone(usize);
+
+ let (mut sender, mut receiver) = channel(NotClone(1));
+ let retained = receiver.snapshot();
+ assert_eq!(sender.send(NotClone(2)), Ok(()));
+ let latest = receiver.snapshot();
+ drop(sender);
+ drop(receiver);
+
+ assert_eq!(*retained, NotClone(1));
+ assert_eq!(*latest, NotClone(2));
+}
+
+#[test]
+fn send_without_receivers_still_stores_the_value() {
+ let (mut sender, receiver) = channel(1);
+ drop(receiver);
+
+ assert_eq!(sender.send(2), Err(NoReceiverError));
+ let mut receiver = sender.receiver();
+ let (waker, _) = counting_waker();
+ assert_eq!(*receiver.snapshot(), 2);
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+}
+
+#[test]
+fn final_publication_precedes_channel_closure() {
+ let (mut sender, mut receiver) = channel(0);
+ let (waker, _) = counting_waker();
+ assert_eq!(sender.send(1), Ok(()));
+ drop(sender);
+
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Ready(Ok(())));
+ assert_eq!(*receiver.snapshot(), 1);
+ assert_eq!(
+ poll_changed(&mut receiver, &waker),
+ Poll::Ready(Err(NoSenderError))
+ );
+}
+
+#[test]
+fn sender_drop_wakes_a_pending_change() {
+ let (sender, mut receiver) = channel(0);
+ let (waker, counter) = counting_waker();
+ let mut changed = Box::pin(receiver.changed());
+ assert_eq!(
+ changed.as_mut().poll(&mut Context::from_waker(&waker)),
+ Poll::Pending
+ );
+
+ drop(sender);
+
+ assert_eq!(counter.0.load(Ordering::SeqCst), 1);
+ assert_eq!(
+ changed.as_mut().poll(&mut Context::from_waker(&waker)),
+ Poll::Ready(Err(NoSenderError))
+ );
+}
+
+#[test]
+fn constant_receiver_never_changes() {
+ #[derive(Debug, PartialEq)]
+ struct NotClone;
+
+ let mut receiver = Receiver::constant(NotClone);
+ let (waker, counter) = counting_waker();
+
+ assert_eq!(poll_changed(&mut receiver, &waker), Poll::Pending);
+ assert_eq!(*receiver.snapshot(), NotClone);
+ assert_eq!(counter.0.load(Ordering::SeqCst), 0);
+}
+
+#[test]
+fn dropping_changed_unregisters_its_waker_and_repoll_replaces_it() {
+ let (mut sender, mut receiver) = channel(0);
+ let (first_waker, first_counter) = counting_waker();
+ let (second_waker, second_counter) = counting_waker();
+
+ {
+ let mut changed = Box::pin(receiver.changed());
+ assert_eq!(
+ changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&first_waker)),
+ Poll::Pending
+ );
+ assert_eq!(
+ changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&second_waker)),
+ Poll::Pending
+ );
+ assert_eq!(sender.send(1), Ok(()));
+ assert_eq!(first_counter.0.load(Ordering::SeqCst), 0);
+ assert_eq!(second_counter.0.load(Ordering::SeqCst), 1);
+ }
+
+ assert_eq!(
+ poll_changed(&mut receiver, &second_waker),
+ Poll::Ready(Ok(()))
+ );
+ let (cancelled_waker, cancelled_counter) = counting_waker();
+ {
+ let mut changed = Box::pin(receiver.changed());
+ assert_eq!(
+ changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&cancelled_waker)),
+ Poll::Pending
+ );
+ }
+ assert_eq!(sender.send(2), Ok(()));
+ assert_eq!(cancelled_counter.0.load(Ordering::SeqCst), 0);
+}
+
+#[test]
+fn publication_wakes_all_registered_receivers() {
+ let (mut sender, mut first_receiver) = channel(0);
+ let mut second_receiver = first_receiver.clone();
+ let mut third_receiver = first_receiver.clone();
+ let (first_waker, first_counter) = counting_waker();
+ let (second_waker, second_counter) = counting_waker();
+ let (third_waker, third_counter) = counting_waker();
+ let mut first_changed = Box::pin(first_receiver.changed());
+ let mut second_changed = Box::pin(second_receiver.changed());
+ let mut third_changed = Box::pin(third_receiver.changed());
+
+ assert_eq!(
+ first_changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&first_waker)),
+ Poll::Pending
+ );
+ assert_eq!(
+ second_changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&second_waker)),
+ Poll::Pending
+ );
+ assert_eq!(
+ third_changed
+ .as_mut()
+ .poll(&mut Context::from_waker(&third_waker)),
+ Poll::Pending
+ );
+
+ assert_eq!(sender.send(1), Ok(()));
+ assert_eq!(first_counter.0.load(Ordering::SeqCst), 1);
+ assert_eq!(second_counter.0.load(Ordering::SeqCst), 1);
+ assert_eq!(third_counter.0.load(Ordering::SeqCst), 1);
+}
+
+#[test]
+fn receiver_churn_removes_waker_entries() {
+ let (mut sender, receiver) = channel(0);
+
+ for _ in 0..1_000 {
+ drop(receiver.clone());
+ }
+
+ assert_eq!(sender.state.receivers.load().len(), 1);
+ drop(receiver);
+ assert!(sender.state.receivers.load().is_empty());
+ assert_eq!(sender.send(1), Err(NoReceiverError));
+}
+
+#[test]
+fn threaded_recv_delivers_each_acknowledged_publication_and_closure() {
+ let (mut sender, mut receiver) = channel(0);
+ let (acknowledgment_sender, acknowledgment_receiver) = mpsc::channel();
+ let (completed_sender, completed_receiver) = mpsc::channel();
+ thread::spawn(move || {
+ futures::executor::block_on(async move {
+ for expected in 1..=1_000 {
+ assert_eq!(receiver.recv().await, Ok(expected));
+ acknowledgment_sender
+ .send(())
+ .expect("publisher is waiting for acknowledgment");
+ }
+ assert_eq!(receiver.recv().await, Err(NoSenderError));
+ });
+ completed_sender.send(()).expect("test is waiting");
+ });
+ for value in 1..=1_000 {
+ assert_eq!(sender.send(value), Ok(()));
+ acknowledgment_receiver
+ .recv_timeout(Duration::from_secs(10))
+ .expect("receiver missed a publication");
+ }
+ drop(sender);
+ completed_receiver
+ .recv_timeout(Duration::from_secs(10))
+ .expect("receiver missed channel closure");
+}
+
+#[test]
+fn concurrent_send_poll_register_and_drop_completes_within_deadline() {
+ const RECEIVER_COUNT: usize = 4;
+ const ITERATIONS: usize = 2_000;
+
+ let (mut sender, receiver) = channel(0);
+ let receivers = (0..RECEIVER_COUNT)
+ .map(|_| receiver.clone())
+ .collect::<Vec<_>>();
+ drop(receiver);
+ let sender_guard = sender.receiver();
+
+ let barrier = Arc::new(Barrier::new(RECEIVER_COUNT + 1));
+ let (completed_sender, completed_receiver) = mpsc::channel();
+
+ for mut receiver in receivers {
+ let barrier = barrier.clone();
+ let completed_sender = completed_sender.clone();
+ thread::spawn(move || {
+ let (waker, _) = counting_waker();
+ barrier.wait();
+ for iteration in 0..ITERATIONS {
+ if poll_changed(&mut receiver, &waker) == Poll::Ready(Err(NoSenderError)) {
+ assert_eq!(*receiver.snapshot(), ITERATIONS);
+ }
+ if iteration % 3 == 0 {
+ let mut clone = receiver.clone();
+ if poll_changed(&mut clone, &waker) == Poll::Ready(Err(NoSenderError)) {
+ assert_eq!(*clone.snapshot(), ITERATIONS);
+ }
+ }
+ }
+ completed_sender
+ .send(())
+ .expect("completion receiver exists");
+ });
+ }
+
+ thread::spawn(move || {
+ let _sender_guard = sender_guard;
+ barrier.wait();
+ for value in 1..=ITERATIONS {
+ assert_eq!(sender.send(value), Ok(()));
+ }
+ completed_sender
+ .send(())
+ .expect("completion receiver exists");
+ });
+
+ for _ in 0..=RECEIVER_COUNT {
+ completed_receiver
+ .recv_timeout(Duration::from_secs(10))
+ .expect("concurrent channel operations exceeded deadline");
+ }
+}
diff --git a/crates/watch/src/watch.rs b/crates/watch/src/watch.rs
index cffe3216c24..828cafdd86d 100644
--- a/crates/watch/src/watch.rs
+++ b/crates/watch/src/watch.rs
@@ -1,4 +1,38 @@
+//! Provides single-producer, multiple-consumer channels that retain the latest value.
+//!
+//! Both [`channel`] and [`snapshot::channel`] coalesce publications: receivers
+//! observe the latest value, not a queue of every value sent. Each receiver tracks
+//! changes independently. The initial value is considered seen, every send counts
+//! as a change even if the value is equal, and an unseen final publication is
+//! delivered before reporting that the sender was dropped.
+//!
+//! # Choosing an implementation
+//!
+//! Use [`channel`] for short-lived reads, low contention, bursty updates, or
+//! frequent receiver creation and destruction. It stores the value behind a
+//! reader/writer lock. [`Receiver::borrow`] returns a read guard and marks the
+//! current version as seen. Holding that guard prevents publication, so release
+//! it promptly and do not hold it across an await.
+//!
+//! Use [`snapshot::channel`] when readers need to retain values without delaying
+//! publication, or channel synchronization must not block a thread. It atomically publishes
+//! immutable snapshots. [`snapshot::Receiver::snapshot`] marks the captured
+//! version as seen and returns an owned handle that can outlive the receiver.
+//! Stable subscriptions suit this implementation better than frequent receiver
+//! creation and destruction.
+//!
+//! # Performance tradeoffs
+//!
+//! | Operation | Lock-based channel | Snapshot channel |
+//! | --- | --- | --- |
+//! | Read | Acquires a read lock | Acquires a reference-counted snapshot |
+//! | Send | Replaces the value in place; visits pending waiters | Allocates a snapshot; visits all registered receivers |
+//! | Pending wait or cancellation | Updates a shared waiter tree under a lock | Updates a per-receiver atomic waker |
+//! | Create or drop a receiver | Constant-time bookkeeping, excluding final destruction | Copies the receiver registry; retries under contention |
+//! | Retain a value | Delays writers | Keeps that version alive without delaying writers |
+
mod error;
+pub mod snapshot;
pub use error::*;
use parking_lot::{RwLock, RwLockReadGuard, RwLockUpgradableReadGuard};