Auto merge of rust-lang#96979 - SabrinaJewson:waker-update, r=workingjubilee

Override `Waker::clone_from` to avoid cloning `Waker`s unnecessarily

This would be very useful for futures — I think it’s pretty much always what they want to do instead of `*waker = cx.waker().clone()`.

Tracking issue: rust-lang#98287

r? rust-lang/libs-api `@rustbot` label +T-libs-api -T-libs

Author: bors

library/core/src/task/wake.rs

@@ -231,6 +231,10 @@ impl fmt::Debug for Context<'_> {
 /// this might be done to wake a future when a blocking function call completes on another
 /// thread.
 ///
+/// Note that it is preferable to use `waker.clone_from(&new_waker)` instead
+/// of `*waker = new_waker.clone()`, as the former will avoid cloning the waker
+/// unnecessarily if the two wakers [wake the same task](Self::will_wake).
+///
 /// [`Future::poll()`]: core::future::Future::poll
 /// [`Poll::Pending`]: core::task::Poll::Pending
 #[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/66401
@@ -302,7 +306,9 @@ impl Waker {
     /// when the `Waker`s would awaken the same task. However, if this function
     /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task.
     ///
-    /// This function is primarily used for optimization purposes.
+    /// This function is primarily used for optimization purposes — for example,
+    /// this type's [`clone_from`](Self::clone_from) implementation uses it to
+    /// avoid cloning the waker when they would wake the same task anyway.
     #[inline]
     #[must_use]
     #[stable(feature = "futures_api", since = "1.36.0")]
@@ -382,6 +388,13 @@ impl Clone for Waker {
             waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
         }
     }
+
+    #[inline]
+    fn clone_from(&mut self, source: &Self) {
+        if !self.will_wake(source) {
+            *self = source.clone();
+        }
+    }
 }
 
 #[stable(feature = "futures_api", since = "1.36.0")]