From d7603f2a83c5de6f3889f288bed3de36d44cf758 Mon Sep 17 00:00:00 2001
From: Eliza Weisman <eliza@elizas.website>
Date: Sat, 20 Jul 2024 11:30:01 -0700
Subject: [PATCH] feat(maitake-sync): rename `EnqueueWait` to `Subscribe`

`maitake-sync`'s `waitmap::Wait' future has an `enqueue` method that
does the same thing as the `subscribe` methods on `WaitCell` and
`WaitQueue`...but has a different name. I think this might be due to
`enqueue` being added earlier or something, or maybe we just weren't
paying attention. Regardless, I figured it was nicer to use the same
name for the method that does the same thing on these different types.

This commit renames the `waitmap::Wait::enqueue` method to `subscribe`,
and the future it returns from `EnqueueWait` to `Subscribe`, analogously
to `WaitQueue` and `WaitCell`. I've left a deprecated type alias and a
deprecated function alias in place, so this isn't a breaking change:
users who reference `Wait::enqueue` or `EnqueueWait` will still be able
to compile their code, but they'll get a warning.

cc @jamesmunns, since I believe you added this API?
---
 maitake-sync/src/wait_map.rs                  | 28 +++++++++++++++----
 .../src/wait_map/tests/alloc_tests.rs         |  6 ++--
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/maitake-sync/src/wait_map.rs b/maitake-sync/src/wait_map.rs
index 2e70b2db..e8924358 100644
--- a/maitake-sync/src/wait_map.rs
+++ b/maitake-sync/src/wait_map.rs
@@ -267,7 +267,7 @@ impl<'map, 'wait, K: PartialEq, V> Wait<'map, K, V> {
     ///     // first pin the `wait` future, to ensure that it does not move
     ///     // until it has been completed.
     ///     pin_mut!(wait);
-    ///     wait.as_mut().enqueue().await.unwrap();
+    ///     wait.as_mut().subscribe().await.unwrap();
     ///
     ///     // We now know the waiter has been enqueued, at this point we could
     ///     // send a message that will cause key == 0 to be returned, without
@@ -285,8 +285,18 @@ impl<'map, 'wait, K: PartialEq, V> Wait<'map, K, V> {
     ///
     /// assert!(matches!(q.wake(&0, 100), WakeOutcome::Woke));
     /// ```
+    pub fn subscribe(self: Pin<&'wait mut Self>) -> Subscribe<'wait, 'map, K, V> {
+        Subscribe { wait: self }
+    }
+
+    /// Deprecated alias for [`Wait::subscribe`]. See that method for details.
+    #[deprecated(
+        since = "0.1.3",
+        note = "renamed to `subscribe` for consistency, use that instead"
+    )]
+    #[allow(deprecated)] // let us use the deprecated type alias
     pub fn enqueue(self: Pin<&'wait mut Self>) -> EnqueueWait<'wait, 'map, K, V> {
-        EnqueueWait { wait: self }
+        self.subscribe()
     }
 }
 
@@ -662,14 +672,14 @@ feature! {
 
 /// A future that ensures a [`Wait`] has been added to a [`WaitMap`].
 ///
-/// See [`Wait::enqueue`] for more information and usage example.
+/// See [`Wait::subscribe`] for more information and usage example.
 #[must_use = "futures do nothing unless `.await`ed or `poll`ed"]
 #[derive(Debug)]
-pub struct EnqueueWait<'a, 'b, K: PartialEq, V> {
+pub struct Subscribe<'a, 'b, K: PartialEq, V> {
     wait: Pin<&'a mut Wait<'b, K, V>>,
 }
 
-impl<'a, 'b, K: PartialEq, V> Future for EnqueueWait<'a, 'b, K, V> {
+impl<'a, 'b, K: PartialEq, V> Future for Subscribe<'a, 'b, K, V> {
     type Output = WaitResult<()>;
 
     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
@@ -682,6 +692,14 @@ impl<'a, 'b, K: PartialEq, V> Future for EnqueueWait<'a, 'b, K, V> {
     }
 }
 
+/// Deprecated alias for [`Subscribe`]. See the [`Wait::subscribe`]
+/// documentation for more details.
+#[deprecated(
+    since = "0.1.3",
+    note = "renamed to `Subscribe` for consistency, use that instead"
+)]
+pub type EnqueueWait<'a, 'b, K, V> = Subscribe<'a, 'b, K, V>;
+
 impl<K: PartialEq, V> Waiter<K, V> {
     /// Wake the task that owns this `Waiter`.
     ///
diff --git a/maitake-sync/src/wait_map/tests/alloc_tests.rs b/maitake-sync/src/wait_map/tests/alloc_tests.rs
index 375c44ed..9d6b6988 100644
--- a/maitake-sync/src/wait_map/tests/alloc_tests.rs
+++ b/maitake-sync/src/wait_map/tests/alloc_tests.rs
@@ -34,7 +34,7 @@ fn enqueue() {
             let wait = q.wait(1);
 
             pin_mut!(wait);
-            wait.as_mut().enqueue().await.unwrap();
+            wait.as_mut().subscribe().await.unwrap();
             ENQUEUED.fetch_add(1, Ordering::Relaxed);
 
             let val = wait.await.unwrap();
@@ -81,7 +81,7 @@ fn duplicate() {
             let wait = q.wait(0);
 
             pin_mut!(wait);
-            wait.as_mut().enqueue().await.unwrap();
+            wait.as_mut().subscribe().await.unwrap();
             ENQUEUED.fetch_add(1, Ordering::Relaxed);
 
             let val = wait.await.unwrap();
@@ -98,7 +98,7 @@ fn duplicate() {
             let wait = q.wait(0);
 
             pin_mut!(wait);
-            wait.as_mut().enqueue().await
+            wait.as_mut().subscribe().await
         }
     });