From 87b823324481d9c6757e31f515bf97b9e1c9b014 Mon Sep 17 00:00:00 2001
From: Dan Gohman
Date: Fri, 12 Jan 2024 14:51:05 -0800
Subject: [PATCH] Switch to `///` comments. (#38)
* Switch to `///` comments.
Per the discussion in WebAssembly/component-model#286, remove some `//`
comments which had been intended as non-documentation comments to `///`
documentation comments.
* Update to the latest wasi-sockets and wasi-io.
Update to the latest wasi-sockets and wasi-io. The only changes are the
addition of some comments, and changing some comments from `//` to `///`.
---
.github/workflows/main.yml | 8 ++---
command.md | 60 ++++++++++++++++++++++++++++++------
imports.md | 60 ++++++++++++++++++++++++++++++------
wit/deps.lock | 8 ++---
wit/deps/io/streams.wit | 11 +++++++
wit/deps/sockets/network.wit | 36 ++++++++++------------
wit/deps/sockets/tcp.wit | 6 ++++
wit/terminal.wit | 18 ++++++-----
8 files changed, 154 insertions(+), 53 deletions(-)
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 6f47982..767e091 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -10,15 +10,15 @@ jobs:
name: Check ABI files are up-to-date
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
+ - uses: actions/checkout@v4
- name: ensure `./wit/deps` are in sync
run: |
- curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.3/wit-deps-x86_64-unknown-linux-musl
+ curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.5/wit-deps-x86_64-unknown-linux-musl
chmod +x wit-deps
./wit-deps lock
git add -N wit/deps
git diff --exit-code
- - uses: WebAssembly/wit-abi-up-to-date@v16
+ - uses: WebAssembly/wit-abi-up-to-date@v17
with:
- wit-bindgen: '0.15.0'
+ wit-bindgen: '0.16.0'
worlds: "command imports"
diff --git a/command.md b/command.md
index 928f2f1..2159bd3 100644
--- a/command.md
+++ b/command.md
@@ -206,6 +206,10 @@ polled for using wasi:io/poll
.
Functions
Perform a non-blocking read from the stream.
+When the source of a read
is binary data, the bytes from the source
+are returned verbatim. When the source of a read
is known to the
+implementation to be text, bytes containing the UTF-8 encoding of the
+text are returned.
This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to len
bytes;
it may return fewer than requested, but not more. The list is
@@ -301,6 +305,11 @@ error.
Perform a write. This function never blocks.
+When the destination of a write
is binary data, the bytes from
+contents
are written verbatim. When the destination of a write
is
+known to the implementation to be text, the bytes of contents
are
+transcoded from UTF-8 into the encoding of the destination and then
+written.
Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.
returns Err(closed) without writing if the stream has closed since
@@ -514,11 +523,19 @@ is ready for reading, before performing the splice
.
own<output-stream
>
+Terminal input.
+In the future, this may include functions for disabling echoing,
+disabling input buffering so that keyboard events are sent through
+immediately, querying supported features, and so on.
Types
The input side of a terminal.
+Terminal output.
+In the future, this may include functions for querying the terminal
+size, being notified of terminal size changes, querying supported
+features, and so on.
Types
@@ -1659,18 +1676,20 @@ combined with a couple of errors that are always possible:
connection-refused
-The connection was forcefully rejected
+
The TCP connection was forcefully rejected
connection-reset
-The connection was reset.
+
The TCP connection was reset.
connection-aborted
-A connection was aborted.
+
A TCP connection was aborted.
datagram-too-large
+The size of a datagram sent to a UDP socket exceeded the maximum
+supported size.
name-unresolvable
@@ -1726,16 +1745,34 @@ combined with a couple of errors that are always possible:
Record Fields
Record Fields
Variant Cases
@@ -2313,6 +2350,11 @@ implicitly bind the socket.
not-in-progress
: A bind
operation is not in progress.
would-block
: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+Implementors note
+When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
+state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
+socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
+and SO_REUSEADDR performs something different entirely.
References
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
diff --git a/imports.md b/imports.md
index a25d734..9109d96 100644
--- a/imports.md
+++ b/imports.md
@@ -201,6 +201,10 @@ polled for using wasi:io/poll
.
Functions
Perform a non-blocking read from the stream.
+When the source of a read
is binary data, the bytes from the source
+are returned verbatim. When the source of a read
is known to the
+implementation to be text, bytes containing the UTF-8 encoding of the
+text are returned.
This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to len
bytes;
it may return fewer than requested, but not more. The list is
@@ -296,6 +300,11 @@ error.
Perform a write. This function never blocks.
+When the destination of a write
is binary data, the bytes from
+contents
are written verbatim. When the destination of a write
is
+known to the implementation to be text, the bytes of contents
are
+transcoded from UTF-8 into the encoding of the destination and then
+written.
Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.
returns Err(closed) without writing if the stream has closed since
@@ -509,11 +518,19 @@ is ready for reading, before performing the splice
.
own<output-stream
>
+Terminal input.
+In the future, this may include functions for disabling echoing,
+disabling input buffering so that keyboard events are sent through
+immediately, querying supported features, and so on.
Types
The input side of a terminal.
+Terminal output.
+In the future, this may include functions for querying the terminal
+size, being notified of terminal size changes, querying supported
+features, and so on.
Types
@@ -1654,18 +1671,20 @@ combined with a couple of errors that are always possible:
connection-refused
-The connection was forcefully rejected
+
The TCP connection was forcefully rejected
connection-reset
-The connection was reset.
+
The TCP connection was reset.
connection-aborted
-A connection was aborted.
+
A TCP connection was aborted.
datagram-too-large
+The size of a datagram sent to a UDP socket exceeded the maximum
+supported size.
name-unresolvable
@@ -1721,16 +1740,34 @@ combined with a couple of errors that are always possible:
Record Fields
Record Fields
Variant Cases
@@ -2308,6 +2345,11 @@ implicitly bind the socket.
not-in-progress
: A bind
operation is not in progress.
would-block
: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+Implementors note
+When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
+state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
+socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
+and SO_REUSEADDR performs something different entirely.
References
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
diff --git a/wit/deps.lock b/wit/deps.lock
index d8a7653..96a4992 100644
--- a/wit/deps.lock
+++ b/wit/deps.lock
@@ -10,8 +10,8 @@ sha512 = "2c242489801a75466986fe014d730fb3aa7b5c6e56a230c8735e6672711b58bcbe92ba
[io]
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
-sha256 = "b622db2755978a49d18d35d84d75f66b2b1ed23d7bf413e5c9e152e190cc7d4b"
-sha512 = "d19c9004e75bf3ebe3e34cff498c3d7fee04cd57a7fba7ed12a0c5ad842ba5715c009de77a152c57da0500f6ca0986b6791b6f022829bdd5a024f7bc114c2ff6"
+sha256 = "7a3c644dfd434f77fdf3f3d3b3caaca9538a0ade785167a3cce0321609f9d4e1"
+sha512 = "2888f12b91359d630b4270f60e3c78855d9b305274ebf8a5decaef8698a74cc85c426823dc708b393f461b85ad991711d7400c2b2a24795001db5aee3ae19c70"
[random]
url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz"
@@ -20,5 +20,5 @@ sha512 = "cc4fa3d178559a89d9d6a376e3359b892158d1e73317c5db1f797ebc6b0b57abf24227
[sockets]
url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
-sha256 = "b5c2e9cc87cefbaef06bbe9978f9bc336da9feee2d51747bc28e10164fc46c39"
-sha512 = "3aea6fe0c768b27d5c5cb3adab5e60dc936198f8b677c2cf6c4d57a0460db87eb779e0b577f1240fb2a6bf3ade49919fbffe39b0137bce3242343e6091cc7510"
+sha256 = "8bcfc6838515714d4bd6cbfb81bb2dd25c6d509c34d593fe6398a08ae825a0be"
+sha512 = "85d23ff1478cd2bee5023c11ed75edaa918f14ad3f0d1142de88b3145a25189c40f4194421f1e234cc893091255c68e5b157e16682bcc5ae0993f78bed606504"
diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit
index f6f7fe0..82e6e07 100644
--- a/wit/deps/io/streams.wit
+++ b/wit/deps/io/streams.wit
@@ -32,6 +32,11 @@ interface streams {
resource input-stream {
/// Perform a non-blocking read from the stream.
///
+ /// When the source of a `read` is binary data, the bytes from the source
+ /// are returned verbatim. When the source of a `read` is known to the
+ /// implementation to be text, bytes containing the UTF-8 encoding of the
+ /// text are returned.
+ ///
/// This function returns a list of bytes containing the read data,
/// when successful. The returned list will contain up to `len` bytes;
/// it may return fewer than requested, but not more. The list is
@@ -111,6 +116,12 @@ interface streams {
/// Perform a write. This function never blocks.
///
+ /// When the destination of a `write` is binary data, the bytes from
+ /// `contents` are written verbatim. When the destination of a `write` is
+ /// known to the implementation to be text, the bytes of `contents` are
+ /// transcoded from UTF-8 into the encoding of the destination and then
+ /// written.
+ ///
/// Precondition: check-write gave permit of Ok(n) and contents has a
/// length of less than or equal to n. Otherwise, this function will trap.
///
diff --git a/wit/deps/sockets/network.wit b/wit/deps/sockets/network.wit
index 6bb07cd..9cadf06 100644
--- a/wit/deps/sockets/network.wit
+++ b/wit/deps/sockets/network.wit
@@ -18,8 +18,6 @@ interface network {
///
/// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
enum error-code {
- // ### GENERAL ERRORS ###
-
/// Unknown error
unknown,
@@ -64,9 +62,6 @@ interface network {
would-block,
-
- // ### TCP & UDP SOCKET ERRORS ###
-
/// The operation is not valid in the socket's current state.
invalid-state,
@@ -83,24 +78,21 @@ interface network {
remote-unreachable,
- // ### TCP SOCKET ERRORS ###
-
- /// The connection was forcefully rejected
+ /// The TCP connection was forcefully rejected
connection-refused,
- /// The connection was reset.
+ /// The TCP connection was reset.
connection-reset,
- /// A connection was aborted.
+ /// A TCP connection was aborted.
connection-aborted,
- // ### UDP SOCKET ERRORS ###
+ /// The size of a datagram sent to a UDP socket exceeded the maximum
+ /// supported size.
datagram-too-large,
- // ### NAME LOOKUP ERRORS ###
-
/// Name does not exist or has no suitable associated IP addresses.
name-unresolvable,
@@ -128,15 +120,21 @@ interface network {
}
record ipv4-socket-address {
- port: u16, // sin_port
- address: ipv4-address, // sin_addr
+ /// sin_port
+ port: u16,
+ /// sin_addr
+ address: ipv4-address,
}
record ipv6-socket-address {
- port: u16, // sin6_port
- flow-info: u32, // sin6_flowinfo
- address: ipv6-address, // sin6_addr
- scope-id: u32, // sin6_scope_id
+ /// sin6_port
+ port: u16,
+ /// sin6_flowinfo
+ flow-info: u32,
+ /// sin6_addr
+ address: ipv6-address,
+ /// sin6_scope_id
+ scope-id: u32,
}
variant ip-socket-address {
diff --git a/wit/deps/sockets/tcp.wit b/wit/deps/sockets/tcp.wit
index b01b65e..337d606 100644
--- a/wit/deps/sockets/tcp.wit
+++ b/wit/deps/sockets/tcp.wit
@@ -42,6 +42,12 @@ interface tcp {
/// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
/// - `not-in-progress`: A `bind` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ ///
+ /// # Implementors note
+ /// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
+ /// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
+ /// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
+ /// and SO_REUSEADDR performs something different entirely.
///
/// # References
/// -
diff --git a/wit/terminal.wit b/wit/terminal.wit
index 4749576..38c724e 100644
--- a/wit/terminal.wit
+++ b/wit/terminal.wit
@@ -1,19 +1,21 @@
+/// Terminal input.
+///
+/// In the future, this may include functions for disabling echoing,
+/// disabling input buffering so that keyboard events are sent through
+/// immediately, querying supported features, and so on.
interface terminal-input {
/// The input side of a terminal.
resource terminal-input;
-
- // In the future, this may include functions for disabling echoing,
- // disabling input buffering so that keyboard events are sent through
- // immediately, querying supported features, and so on.
}
+/// Terminal output.
+///
+/// In the future, this may include functions for querying the terminal
+/// size, being notified of terminal size changes, querying supported
+/// features, and so on.
interface terminal-output {
/// The output side of a terminal.
resource terminal-output;
-
- // In the future, this may include functions for querying the terminal
- // size, being notified of terminal size changes, querying supported
- // features, and so on.
}
/// An interface providing an optional `terminal-input` for stdin as a