wakebyref

Wake_by_ref, often written wake_by_ref, is a pattern in asynchronous programming, particularly in Rust, referring to waking a task without consuming the wake handle. It contrasts with wake, which takes ownership of the waker.

In Rust’s async runtime, a Waker represents a handle that can be used to wake a sleeping task. The Waker provides two methods: wake() and wake_by_ref(). The wake method consumes the Waker, moving it, while wake_by_ref() borrows the Waker and wakes the task without consuming it. This distinction matters in poll-based futures, where the same Waker may need to be reused or stored after waking.

Wake_by_ref is used to re-schedule a task without transferring ownership of the waker. It enables efficient coordination in executors and runtimes like Tokio, where a future can signal readiness multiple times without creating new waker instances. If a future needs to wake from within a context that still holds a reference to the Waker, wake_by_ref is the appropriate choice.

Implementation-wise, a Waker is constructed from a RawWaker, and wake_by_ref forwards the wake request to the underlying wake mechanism without consuming the Waker. This approach helps avoid unnecessary allocations or moves and preserves correct ownership semantics in asynchronous code.

Example usage (in plain text): within a poll implementation, one may call cx.waker().wake_by_ref() to re-schedule the task without taking ownership of the waker. This pattern is common in futures-based code and is documented as part of the Waker API in Rust’s standard library and associated async runtimes.

See also: Future, Waker, RawWaker, Tokio, async-std.