Crate smelling_salts

Abstraction over OS APIs to handle asynchronous device waking.

Getting Started

Most devices are represented as file descriptors on unix-like operating systems (MacOS also has run loops). On Windows, devices are usually sockets or handles. WebAssembly running in the browser doesn’t have a equivalent. To get around these device backend differences, Smelling Salts exposed an OsDevice type which has From conversions implemented for the platform types.

An OsDevice by itself isn’t that useful, though. When you have a handle to a device, you want to asynchronously watch it for events. For this, you construct a Device, which implements Notify. But, general devices aren’t that useful either, so you’ll need to wrap it in your own custom type. Usually, you will filter out some of the events, so you’ll need to implement Notify.

Here’s a simple example implementing a Notify for stdin line reading:

use std::{
    io::{self, BufRead, BufReader},
    os::fd::AsFd,
};

use async_main::{async_main, Spawn};
use pasts::prelude::*;
use smelling_salts::{Device, Watch};

/// A `Stdin` device future.
pub struct Stdin(BufReader<Device>);

impl Default for Stdin {
    fn default() -> Self {
        Self::new()
    }
}

impl Stdin {
    /// Create a new `Stdin` device handle.
    pub fn new() -> Self {
        let owned_fd = io::stdin().as_fd().try_clone_to_owned().unwrap();
        let device = Device::new(owned_fd, Watch::INPUT);

        Self(BufReader::new(device))
    }
}

impl Notify for Stdin {
    type Event = String;

    fn poll_next(
        mut self: Pin<&mut Self>,
        task: &mut Task<'_>,
    ) -> Poll<String> {
        while let Ready(()) = Pin::new(self.0.get_mut()).poll_next(task) {
            let mut string = String::new();
            let Err(e) = self.0.read_line(&mut string) else {
                string.pop();
                return Ready(string);
            };

            dbg!(e);
        }

        Pending
    }
}

#[async_main]
async fn main(_spawner: impl Spawn) {
    let mut stdin = Stdin::new();

    loop {
        let you_said = stdin.next().await;

        println!("You said: \"{you_said}\"");
    }
}

Structs

• Device
  An owned device handle that’s being watched for wake events
• OsDevice
  An owned handle to an unwatched OS device
• Watch
  A bitfield specifying which events to watch for