Improve documentation and simplify API

Author: timokroeger

README.md

@@ -4,27 +4,33 @@ Per-thread async rust executor for windows.
 Each task is backed by a [message-only window][1].
 The executor thread runs the native [windows message loop][2] which dispatches wake messages to the tasks window procedure which polls the task future.
 
-As a thin wrapper for WinAPI calls the whole executor is implemented in around 300 lines of code.
-
 ## Features
 
-- Easy data sharing within a thread because `Send` or `Sync` is not required for the task future
-- A task can spawn new tasks on the same thread
+- Easy data sharing within a thread because `Send` or `Sync` is not required for the task future.
+- Runs multiply tasks on the same thread. Tasks can spawn new tasks and await the result.
 - Modal windows like menus do not block other tasks running on the same thread.
 - Helper code to implement window procedures with closures that can have state.
 
+## Alternative Backend: `async-task`
+
+Selected by the `backend-async-task` cargo feature.
+Uses `async-task`s task abstraction instead of a window per task to store the future.
+Scheduling a tasks means posting its runnable to the threads message queue (similar to `windows-executor` see below).
+
 ## Comparison with similar crates
 
+Both of those listed crates run one taks/future per thread in their and expose
+only `block_on()`.
+[Is block_on an executor?](https://github.com/rust-lang/async-book/issues/219)
+
 ### [`windows-exeuctor`](https://github.com/haileys/windows-executor/)
 
-- Supports only a single task.
-- Polls directly from the message loop.
+- Polls its future directly from the message loop.
 - Does not create a windows at all: Waker stores the message loops thread id and notifies it with `PostThreadMessage()`.
-- Does not quit the message loop correctly when the task futures returns.
+- Does not close the threads message loop (no `PostQuitMessage()` call) when the task futures returns.
 
 ### [`windows-async-rs`](https://github.com/saelay/windows-async-rs/)
 
-- Supports only a single task.
 - Polls directly from the message loop even when receiving broadcast messages unrelated to the task.
 - Questionable use of unsafe code
 

examples/basic.rs

@@ -1,6 +1,6 @@
 use std::{future::poll_fn, task::Poll};
 
-use winmsg_executor::{spawn, MessageLoop};
+use winmsg_executor::{block_on, spawn};
 
 async fn poll_n_times(mut n_poll: usize) {
     poll_fn(|cx| {
@@ -18,8 +18,7 @@ async fn poll_n_times(mut n_poll: usize) {
 
 fn main() {
     println!("hello");
-    let msg_loop = MessageLoop::new();
-    msg_loop.block_on(async {
+    block_on(async {
         let task = spawn(async {
             println!("async hello 1");
             poll_n_times(3).await;

examples/threads.rs

@@ -1,6 +1,6 @@
 use std::{future::poll_fn, task::Poll, thread};
 
-use winmsg_executor::MessageLoop;
+use winmsg_executor::block_on;
 
 async fn poll_n_times(mut n_poll: usize) {
     poll_fn(|cx| {
@@ -19,8 +19,7 @@ async fn poll_n_times(mut n_poll: usize) {
 fn main() {
     thread::spawn(|| {
         println!("thread hello");
-        let msg_loop = MessageLoop::new();
-        msg_loop.block_on(async {
+        block_on(async {
             println!("thread async hello");
             poll_n_times(3).await;
             println!("thread async bye");
@@ -29,8 +28,7 @@ fn main() {
     });
 
     println!("main hello");
-    let msg_loop = MessageLoop::new();
-    msg_loop.block_on(async {
+    block_on(async {
         println!("main async hello");
         poll_n_times(3).await;
         println!("main async bye");

src/backend/mod.rs

@@ -1,3 +1,6 @@
+#[cfg(all(feature = "backend-windows", feature = "backend-async-task"))]
+compile_error!("only one `backend-*` feature can be selected at a time");
+
 #[cfg(feature = "backend-windows")]
 #[path = "window.rs"]
 mod _backend;

src/backend/window.rs

@@ -19,7 +19,7 @@ pub const fn dispatch(_msg: &MSG) -> bool {
 
 const MSG_ID_WAKE: u32 = WM_USER;
 
-// Use same terminology as `async-task` crate.
+// Same terminology as `async-task` crate.
 enum TaskState<F: Future> {
     Running(F, Option<Waker>),
     Completed(F::Output),
@@ -40,7 +40,7 @@ unsafe impl<F: Future> Sync for Task<F> {}
 impl<F: Future> Wake for Task<F> {
     fn wake(self: Arc<Self>) {
         // Ideally the waker would know if the task has completed to decide if
-        // its necessary to send a wake message. But that also means access to
+        // its necessary to send a wake message. But that also means access that
         // task state must be made thread safe. Instead, always post the wake
         // message and let the receiver side (which runs on the same thread the
         // task was created on) decide if a task needs to be polled.

src/lib.rs

@@ -6,7 +6,6 @@ pub mod util;
 use std::{
     cell::Cell,
     future::Future,
-    marker::PhantomData,
     mem::MaybeUninit,
     pin::pin,
     ptr,
@@ -17,107 +16,77 @@ use windows_sys::Win32::{
     Foundation::*, System::Threading::GetCurrentThreadId, UI::WindowsAndMessaging::*,
 };
 
-thread_local! {
-    static MESSAGE_LOOP_RUNNING: Cell<bool> = const { Cell::new(false) };
-}
-
-/// Represents this threads [windows message loop][1].
-/// To execute async code within the message loop use the
-/// [`block_on()`](MessageLoop::block_on) method.
+/// Runs a future to completion on the calling threads message loop.
+///
+/// This runs the provided future on the current thread, blocking until it
+/// is complete. Any tasks spawned which the future spawns internally will
+/// be executed no the same thread.
 ///
-/// [1]: https://learn.microsoft.com/en-us/windows/win32/winmsg/messages-and-message-queues
-pub struct MessageLoop {
-    _not_send: PhantomData<*const ()>,
+/// Any spawned tasks will be suspended after `block_on` returns. Calling
+/// `block_on` again will resume previously spawned tasks.
+///
+/// # Panics
+///
+/// Panics when the message loops is running already. This happens when
+/// `block_on` or `run` is called from async tasks running on this executor.
+pub fn block_on<T: 'static>(future: impl Future<Output = T> + 'static) -> T {
+    // Wrap the future so it quits the message loop when finished.
+    let task = backend::spawn(async move {
+        let result = future.await;
+        unsafe { PostQuitMessage(0) };
+        result
+    });
+    run_message_loop();
+    poll_assume_ready(task)
 }
 
-impl Default for MessageLoop {
-    fn default() -> Self {
-        Self::new()
-    }
-}
+/// Runs the message loop.
+///
+/// Executes previously [`spawn`]ed tasks.
+///
+/// # Panics
+///
+/// Panics when the message loops is running already. This happens when
+/// `block_on` or `run` is called from async tasks running on this executor.
+pub fn run_message_loop() {
+    thread_local!(static MESSAGE_LOOP_RUNNING: Cell<bool> = const { Cell::new(false) });
+    assert!(
+        !MESSAGE_LOOP_RUNNING.replace(true),
+        "a message loop is running already"
+    );
 
-impl MessageLoop {
-    /// Creates a message queue for the current thread but does not run the
-    /// dispatch loop for it yet.
-    #[must_use]
-    pub const fn new() -> Self {
-        Self {
-            _not_send: PhantomData,
+    // Any modal window (i.e. a right-click menu) blocks the main message loop
+    // and dispatches messages internally. To keep the executor running use a
+    // hook to get access to modal windows internal message loop.
+    unsafe extern "system" fn hook_proc(code: i32, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
+        if code >= 0 && backend::dispatch(&*(lparam as *const MSG)) {
+            1
+        } else {
+            CallNextHookEx(0, code, wparam, lparam)
         }
     }
+    let hook = unsafe { SetWindowsHookExA(WH_MSGFILTER, Some(hook_proc), 0, GetCurrentThreadId()) };
 
-    /// Runs a future to completion on the message loop.
-    ///
-    /// This runs the provided future on the current thread, blocking until it
-    /// is complete. Any tasks spawned which the future spawns internally will
-    /// be executed no the same thread.
-    ///
-    /// Any spawned tasks will be suspended after `block_on` returns. Calling
-    /// `block_on` again will resume previously spawned tasks.
-    ///
-    /// # Panics
-    ///
-    /// Panics when the message loops is running already. This happens when
-    /// `block_on` or `run` is called from async tasks running on this executor.
-    pub fn block_on<T: 'static>(&self, future: impl Future<Output = T> + 'static) -> T {
-        // Wrap the future so it quits the message loop when finished.
-        let task = backend::spawn(async move {
-            let result = future.await;
-            unsafe { PostQuitMessage(0) };
-            result
-        });
-        self.run();
-        poll_assume_ready(task)
-    }
-
-    /// Runs the message loop.
-    ///
-    /// Executes previously [`spawn`]ed tasks.
-    ///
-    /// # Panics
-    ///
-    /// Panics when the message loops is running already. This happens when
-    /// `block_on` or `run` is called from async tasks running on this executor.
-    pub fn run(&self) {
-        assert!(
-            !MESSAGE_LOOP_RUNNING.replace(true),
-            "a message loop is running already"
-        );
-
-        // Any modal window (i.e. a right-click menu) blocks the main message loop
-        // and dispatches messages internally. To keep the executor running use a
-        // hook to get access to modal windows internal message loop.
-        unsafe extern "system" fn hook_proc(code: i32, wparam: WPARAM, lparam: LPARAM) -> LRESULT {
-            if code >= 0 && backend::dispatch(&*(lparam as *const MSG)) {
-                1
-            } else {
-                CallNextHookEx(0, code, wparam, lparam)
-            }
-        }
-        let hook =
-            unsafe { SetWindowsHookExA(WH_MSGFILTER, Some(hook_proc), 0, GetCurrentThreadId()) };
-
-        loop {
-            let mut msg = MaybeUninit::uninit();
-            unsafe {
-                let ret = GetMessageA(msg.as_mut_ptr(), 0, 0, 0);
-                let msg = msg.assume_init();
-                match ret {
-                    1 => {
-                        if !backend::dispatch(&msg) {
-                            TranslateMessage(&msg);
-                            DispatchMessageA(&msg);
-                        }
+    loop {
+        let mut msg = MaybeUninit::uninit();
+        unsafe {
+            let ret = GetMessageA(msg.as_mut_ptr(), 0, 0, 0);
+            let msg = msg.assume_init();
+            match ret {
+                1 => {
+                    if !backend::dispatch(&msg) {
+                        TranslateMessage(&msg);
+                        DispatchMessageA(&msg);
                     }
-                    0 => break,
-                    _ => unreachable!(),
                 }
+                0 => break,
+                _ => unreachable!(),
             }
         }
-
-        unsafe { UnhookWindowsHookEx(hook) };
-        MESSAGE_LOOP_RUNNING.set(false);
     }
+
+    unsafe { UnhookWindowsHookEx(hook) };
+    MESSAGE_LOOP_RUNNING.set(false);
 }
 
 fn poll_assume_ready<T>(future: impl Future<Output = T>) -> T {
@@ -136,6 +105,8 @@ fn poll_assume_ready<T>(future: impl Future<Output = T>) -> T {
     }
 }
 
+/// An owned permission to join on a task (await its termination).
+///
 /// If a `JoinHandle` is dropped, then its task continues running in the background
 /// and its return value is lost.
 pub type JoinHandle<F> = backend::JoinHandle<F>;

src/util/mod.rs

@@ -1,2 +1,4 @@
+//! Helper code to work with windows.
+
 mod window;
 pub use window::*;