From ee24d1fa5e845473359f2ee213af31926dc316c4 Mon Sep 17 00:00:00 2001
From: Pat Hickey <phickey@fastly.com>
Date: Tue, 31 Oct 2023 12:53:57 -0700
Subject: [PATCH] pollable: add methods block & ready, rename poll-list to poll
 (#54)

* rename `poll-one` to `pollable.block`, and add `ready` method

The name `poll-one` is very easily confused with `poll-oneoff`, the
previous name of `poll-list` during WASI preview 1 and much of the
development of Preview 2.

Inspecting if a poll is ready without blocking was requested in https://github.com/WebAssembly/wasi-io/issues/51

* rename `poll-list` to `poll`

With `poll-one` renamed to `pollable.block`, there is no longer a
distinction required between `poll-list` and `poll-one`, so change
this name to the simplest name that can possibly work.
---
 imports.md   | 34 +++++++++++++++++++++++-----------
 wit/poll.wit | 25 ++++++++++++++++---------
 2 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/imports.md b/imports.md
index 3f38661..e08b326 100644
--- a/imports.md
+++ b/imports.md
@@ -15,7 +15,27 @@ at once.</p>
 <h4><a name="pollable"><code>resource pollable</code></a></h4>
 <hr />
 <h3>Functions</h3>
-<h4><a name="poll_list"><code>poll-list: func</code></a></h4>
+<h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
+<p>Return the readiness of a pollable. This function never blocks.</p>
+<p>Returns <code>true</code> when the pollable is ready, and <code>false</code> otherwise.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_pollable.ready.self"><code>self</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_pollable.ready.0"></a> <code>bool</code></li>
+</ul>
+<h4><a name="method_pollable.block"><code>[method]pollable.block: func</code></a></h4>
+<p><code>block</code> returns immediately if the pollable is ready, and otherwise
+blocks until ready.</p>
+<p>This function is equivalent to calling <code>poll.poll</code> on a list
+containing only this pollable.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_pollable.block.self"><code>self</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
+</ul>
+<h4><a name="poll"><code>poll: func</code></a></h4>
 <p>Poll for completion on a set of pollables.</p>
 <p>This function takes a list of pollables, which identify I/O sources of
 interest, and waits until one or more of the events is ready for I/O.</p>
@@ -31,19 +51,11 @@ the pollables has an error, it is indicated by marking the source as
 being reaedy for I/O.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="poll_list.in"><code>in</code></a>: list&lt;borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;&gt;</li>
+<li><a name="poll.in"><code>in</code></a>: list&lt;borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="poll_list.0"></a> list&lt;<code>u32</code>&gt;</li>
-</ul>
-<h4><a name="poll_one"><code>poll-one: func</code></a></h4>
-<p>Poll for completion on a single pollable.</p>
-<p>This function is similar to <a href="#poll_list"><code>poll-list</code></a>, but operates on only a single
-pollable. When it returns, the handle is ready for I/O.</p>
-<h5>Params</h5>
-<ul>
-<li><a name="poll_one.in"><code>in</code></a>: borrow&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
+<li><a name="poll.0"></a> list&lt;<code>u32</code>&gt;</li>
 </ul>
 <h2><a name="wasi:io_streams">Import interface wasi:io/streams</a></h2>
 <p>WASI I/O is an I/O abstraction API which is currently focused on providing
diff --git a/wit/poll.wit b/wit/poll.wit
index 254f534..0829a7d 100644
--- a/wit/poll.wit
+++ b/wit/poll.wit
@@ -3,8 +3,21 @@ package wasi:io;
 /// A poll API intended to let users wait for I/O events on multiple handles
 /// at once.
 interface poll {
-    /// A "pollable" handle.
-    resource pollable;
+    /// `pollable` epresents a single I/O event which may be ready, or not.
+    resource pollable {
+
+      /// Return the readiness of a pollable. This function never blocks.
+      ///
+      /// Returns `true` when the pollable is ready, and `false` otherwise.
+      ready: func() -> bool;
+
+      /// `block` returns immediately if the pollable is ready, and otherwise
+      /// blocks until ready.
+      ///
+      /// This function is equivalent to calling `poll.poll` on a list
+      /// containing only this pollable.
+      block: func();
+    }
 
     /// Poll for completion on a set of pollables.
     ///
@@ -24,11 +37,5 @@ interface poll {
     /// do any I/O so it doesn't fail. If any of the I/O sources identified by
     /// the pollables has an error, it is indicated by marking the source as
     /// being reaedy for I/O.
-    poll-list: func(in: list<borrow<pollable>>) -> list<u32>;
-
-    /// Poll for completion on a single pollable.
-    ///
-    /// This function is similar to `poll-list`, but operates on only a single
-    /// pollable. When it returns, the handle is ready for I/O.
-    poll-one: func(in: borrow<pollable>);
+    poll: func(in: list<borrow<pollable>>) -> list<u32>;
 }