pub struct Waitable<T>(/* private fields */);Expand description
A waitable handle registered in the reactor.
Some handles in Windows are “waitable”, which means that they emit a “readiness” signal after some event occurs. This function can be used to wait for such events to occur on a handle. This function can be used in addition to regular socket polling.
Waitable objects include the following:
- Console inputs
- Waitable events
- Mutexes
- Processes
- Semaphores
- Threads
- Timer
This structure can be used to wait for any of these objects to become ready.
§Implementation
The current implementation waits on the handle by registering it in the application-global
Win32 threadpool. However, in the future it may be possible to migrate to an implementation
on Windows 10 that uses a mechanism similar to MsgWaitForMultipleObjectsEx.
§Caveats
Read the documentation for the Async type for more information regarding the
abilities and caveats with using this type.
Implementations§
Source§impl<T: AsHandle> Waitable<T>
impl<T: AsHandle> Waitable<T>
Sourcepub fn new(handle: T) -> Result<Self>
pub fn new(handle: T) -> Result<Self>
Create a new Waitable around a waitable handle.
§Examples
use std::process::Command;
use async_io::os::windows::Waitable;
// Create a new process to wait for.
let mut child = Command::new("sleep").arg("5").spawn().unwrap();
// Wrap the process in an `Async` object that waits for it to exit.
let process = Waitable::new(child).unwrap();
// Wait for the process to exit.
process.ready().await.unwrap();Source§impl<T> Waitable<T>
impl<T> Waitable<T>
Sourcepub unsafe fn get_mut(&mut self) -> &mut T
pub unsafe fn get_mut(&mut self) -> &mut T
Get a mutable reference to the inner handle.
§Safety
The underlying I/O source must not be dropped or moved out using this function.
Sourcepub fn into_inner(self) -> Result<T>
pub fn into_inner(self) -> Result<T>
Consumes the Waitable, returning the inner handle.
Sourcepub fn ready(&self) -> Ready<'_, T> ⓘ
pub fn ready(&self) -> Ready<'_, T> ⓘ
Waits until the Waitable object is ready.
This method completes when the underlying Waitable object has completed. See the documentation
for the Waitable object for more information.
§Examples
use std::process::Command;
use async_io::os::windows::Waitable;
let child = Command::new("sleep").arg("5").spawn()?;
let process = Waitable::new(child)?;
// Wait for the process to exit.
process.ready().await?;Sourcepub fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
pub fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<()>>
Polls the I/O handle for readiness.
When this method returns Poll::Ready, that means that the OS has delivered a notification
that the underlying Waitable object is ready. See the documentation for the Waitable
object for more information.
§Caveats
Two different tasks should not call this method concurrently. Otherwise, conflicting tasks will just keep waking each other in turn, thus wasting CPU time.
§Examples
use std::process::Command;
use async_io::os::windows::Waitable;
use futures_lite::future;
let child = Command::new("sleep").arg("5").spawn()?;
let process = Waitable::new(child)?;
// Wait for the process to exit.
future::poll_fn(|cx| process.poll_ready(cx)).await?;