Skip to content

Commit

Permalink
doc: change WASI Preview2 -> WASI 0.2
Browse files Browse the repository at this point in the history
  • Loading branch information
yoshuawuyts committed Oct 3, 2024
1 parent ba00c88 commit efa4eb9
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 45 deletions.
102 changes: 62 additions & 40 deletions imports.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
<ul>
<li>Imports:
<ul>
<li>interface <a href="#wasi_io_error_0_2_2"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi_sockets_network_0_2_2"><code>wasi:sockets/[email protected]</code></a></li>
<li>interface <a href="#wasi_sockets_instance_network_0_2_2"><code>wasi:sockets/[email protected]</code></a></li>
<li>interface <a href="#wasi_io_poll_0_2_2"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi_sockets_udp_0_2_2"><code>wasi:sockets/[email protected]</code></a></li>
<li>interface <a href="#wasi_sockets_udp_create_socket_0_2_2"><code>wasi:sockets/[email protected]</code></a></li>
<li>interface <a href="#wasi_io_error_0_2_2"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi_io_streams_0_2_2"><code>wasi:io/[email protected]</code></a></li>
<li>interface <a href="#wasi_clocks_monotonic_clock_0_2_2"><code>wasi:clocks/[email protected]</code></a></li>
<li>interface <a href="#wasi_sockets_tcp_0_2_2"><code>wasi:sockets/[email protected]</code></a></li>
Expand All @@ -16,10 +16,46 @@
</ul>
</li>
</ul>
<h2><a id="wasi_io_error_0_2_2"></a>Import interface wasi:io/[email protected]</h2>
<hr />
<h3>Types</h3>
<h4><a id="error"></a><code>resource error</code></h4>
<p>A resource which represents some error information.</p>
<p>The only method provided by this resource is <code>to-debug-string</code>,
which provides some human-readable information about the error.</p>
<p>In the <code>wasi:io</code> package, this resource is returned through the
<code>wasi:io/streams/stream-error</code> type.</p>
<p>To provide more specific error information, other interfaces may
offer functions to &quot;downcast&quot; this error into more specific types. For example,
errors returned from streams derived from filesystem types can be described using
the filesystem's own error-code type. This is done using the function
<code>wasi:filesystem/types/filesystem-error-code</code>, which takes a <code>borrow&lt;error&gt;</code>
parameter and returns an <code>option&lt;wasi:filesystem/types/error-code&gt;</code>.</p>
<h2>The set of functions which can &quot;downcast&quot; an <a href="#error"><code>error</code></a> into a more
concrete type is open.</h2>
<h3>Functions</h3>
<h4><a id="method_error_to_debug_string"></a><code>[method]error.to-debug-string: func</code></h4>
<p>Returns a string that is suitable to assist humans in debugging
this error.</p>
<p>WARNING: The returned string should not be consumed mechanically!
It may change across platforms, hosts, or other implementation
details. Parsing this string is a major platform-compatibility
hazard.</p>
<h5>Params</h5>
<ul>
<li><a id="method_error_to_debug_string.self"></a><code>self</code>: borrow&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
</ul>
<h5>Return values</h5>
<ul>
<li><a id="method_error_to_debug_string.0"></a> <code>string</code></li>
</ul>
<h2><a id="wasi_sockets_network_0_2_2"></a>Import interface wasi:sockets/[email protected]</h2>
<hr />
<h3>Types</h3>
<h4><a id="network"></a><code>resource network</code></h4>
<h4><a id="error"></a><code>type error</code></h4>
<p><a href="#error"><a href="#error"><code>error</code></a></a></p>
<p>
#### <a id="network"></a>`resource network`
<p>An opaque resource that represents access to (a subset of) the network.
This enables context-based security for networking.
There is no need for this to map 1:1 to a physical network interface.</p>
Expand Down Expand Up @@ -209,6 +245,25 @@ supported size.
<li><a id="ip_socket_address.ipv4"></a><code>ipv4</code>: <a href="#ipv4_socket_address"><a href="#ipv4_socket_address"><code>ipv4-socket-address</code></a></a></li>
<li><a id="ip_socket_address.ipv6"></a><code>ipv6</code>: <a href="#ipv6_socket_address"><a href="#ipv6_socket_address"><code>ipv6-socket-address</code></a></a></li>
</ul>
<hr />
<h3>Functions</h3>
<h4><a id="network_error_code"></a><code>network-error-code: func</code></h4>
<p>Attempts to extract a network-related <a href="#error_code"><code>error-code</code></a> from the stream
<a href="#error"><code>error</code></a> provided.</p>
<p>Stream operations which return <a href="#stream_error.last_operation_failed"><code>stream-error::last-operation-failed</code></a>
have a payload with more information about the operation that failed.
This payload can be passed through to this function to see if there's
network-related information about the error to return.</p>
<p>Note that this function is fallible because not all stream-related
errors are network-related errors.</p>
<h5>Params</h5>
<ul>
<li><a id="network_error_code.err"></a><code>err</code>: borrow&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
</ul>
<h5>Return values</h5>
<ul>
<li><a id="network_error_code.0"></a> option&lt;<a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
</ul>
<h2><a id="wasi_sockets_instance_network_0_2_2"></a>Import interface wasi:sockets/[email protected]</h2>
<p>This interface provides a value-export of the default network handle..</p>
<hr />
Expand Down Expand Up @@ -563,7 +618,7 @@ I.e. after setting a value, reading the same setting back may return a different
</ul>
<h4><a id="method_udp_socket_subscribe"></a><code>[method]udp-socket.subscribe: func</code></h4>
<p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once the socket is ready for I/O.</p>
<p>Note: this function is here for WASI Preview2 only.
<p>Note: this function is here for WASI 0.2 only.
It's planned to be removed when <code>future</code> is natively supported in Preview3.</p>
<h5>Params</h5>
<ul>
Expand Down Expand Up @@ -610,7 +665,7 @@ This function never returns <code>error(would-block)</code>.</li>
</ul>
<h4><a id="method_incoming_datagram_stream_subscribe"></a><code>[method]incoming-datagram-stream.subscribe: func</code></h4>
<p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once the stream is ready to receive again.</p>
<p>Note: this function is here for WASI Preview2 only.
<p>Note: this function is here for WASI 0.2 only.
It's planned to be removed when <code>future</code> is natively supported in Preview3.</p>
<h5>Params</h5>
<ul>
Expand Down Expand Up @@ -681,7 +736,7 @@ either <code>check-send</code> was not called or <code>datagrams</code> contains
</ul>
<h4><a id="method_outgoing_datagram_stream_subscribe"></a><code>[method]outgoing-datagram-stream.subscribe: func</code></h4>
<p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once the stream is ready to send again.</p>
<p>Note: this function is here for WASI Preview2 only.
<p>Note: this function is here for WASI 0.2 only.
It's planned to be removed when <code>future</code> is natively supported in Preview3.</p>
<h5>Params</h5>
<ul>
Expand Down Expand Up @@ -736,39 +791,6 @@ the socket is effectively an in-memory configuration object, unable to communica
<ul>
<li><a id="create_udp_socket.0"></a> result&lt;own&lt;<a href="#udp_socket"><a href="#udp_socket"><code>udp-socket</code></a></a>&gt;, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
</ul>
<h2><a id="wasi_io_error_0_2_2"></a>Import interface wasi:io/[email protected]</h2>
<hr />
<h3>Types</h3>
<h4><a id="error"></a><code>resource error</code></h4>
<p>A resource which represents some error information.</p>
<p>The only method provided by this resource is <code>to-debug-string</code>,
which provides some human-readable information about the error.</p>
<p>In the <code>wasi:io</code> package, this resource is returned through the
<code>wasi:io/streams/stream-error</code> type.</p>
<p>To provide more specific error information, other interfaces may
offer functions to &quot;downcast&quot; this error into more specific types. For example,
errors returned from streams derived from filesystem types can be described using
the filesystem's own error-code type. This is done using the function
<code>wasi:filesystem/types/filesystem-error-code</code>, which takes a <code>borrow&lt;error&gt;</code>
parameter and returns an <code>option&lt;wasi:filesystem/types/error-code&gt;</code>.</p>
<h2>The set of functions which can &quot;downcast&quot; an <a href="#error"><code>error</code></a> into a more
concrete type is open.</h2>
<h3>Functions</h3>
<h4><a id="method_error_to_debug_string"></a><code>[method]error.to-debug-string: func</code></h4>
<p>Returns a string that is suitable to assist humans in debugging
this error.</p>
<p>WARNING: The returned string should not be consumed mechanically!
It may change across platforms, hosts, or other implementation
details. Parsing this string is a major platform-compatibility
hazard.</p>
<h5>Params</h5>
<ul>
<li><a id="method_error_to_debug_string.self"></a><code>self</code>: borrow&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
</ul>
<h5>Return values</h5>
<ul>
<li><a id="method_error_to_debug_string.0"></a> <code>string</code></li>
</ul>
<h2><a id="wasi_io_streams_0_2_2"></a>Import interface wasi:io/[email protected]</h2>
<p>WASI I/O is an I/O abstraction API which is currently focused on providing
stream types.</p>
Expand Down Expand Up @@ -1705,7 +1727,7 @@ in progress at the time of calling <code>subscribe</code> (if any). Theoreticall
(re)used for the remainder of the socket's lifetime.</p>
<p>See <a href="https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness">https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness</a>
for more information.</p>
<p>Note: this function is here for WASI Preview2 only.
<p>Note: this function is here for WASI 0.2 only.
It's planned to be removed when <code>future</code> is natively supported in Preview3.</p>
<h5>Params</h5>
<ul>
Expand Down Expand Up @@ -1864,7 +1886,7 @@ addresses have been exhausted, this function returns <code>none</code>.</p>
</ul>
<h4><a id="method_resolve_address_stream_subscribe"></a><code>[method]resolve-address-stream.subscribe: func</code></h4>
<p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once the stream is ready for I/O.</p>
<p>Note: this function is here for WASI Preview2 only.
<p>Note: this function is here for WASI 0.2 only.
It's planned to be removed when <code>future</code> is natively supported in Preview3.</p>
<h5>Params</h5>
<ul>
Expand Down
2 changes: 1 addition & 1 deletion wit/ip-name-lookup.wit
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ interface ip-name-lookup {

/// Create a `pollable` which will resolve once the stream is ready for I/O.
///
/// Note: this function is here for WASI Preview2 only.
/// Note: this function is here for WASI 0.2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
Expand Down
2 changes: 1 addition & 1 deletion wit/tcp.wit
Original file line number Diff line number Diff line change
Expand Up @@ -353,7 +353,7 @@ interface tcp {
/// See <https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness>
/// for more information.
///
/// Note: this function is here for WASI Preview2 only.
/// Note: this function is here for WASI 0.2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
Expand Down
6 changes: 3 additions & 3 deletions wit/udp.wit
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ interface udp {

/// Create a `pollable` which will resolve once the socket is ready for I/O.
///
/// Note: this function is here for WASI Preview2 only.
/// Note: this function is here for WASI 0.2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
Expand Down Expand Up @@ -220,7 +220,7 @@ interface udp {

/// Create a `pollable` which will resolve once the stream is ready to receive again.
///
/// Note: this function is here for WASI Preview2 only.
/// Note: this function is here for WASI 0.2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
Expand Down Expand Up @@ -280,7 +280,7 @@ interface udp {

/// Create a `pollable` which will resolve once the stream is ready to send again.
///
/// Note: this function is here for WASI Preview2 only.
/// Note: this function is here for WASI 0.2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
Expand Down

0 comments on commit efa4eb9

Please sign in to comment.