From 174dbd7fa134672e594fd38dba9acfb53afaf312 Mon Sep 17 00:00:00 2001 From: Pat Hickey Date: Wed, 24 Jan 2024 11:56:16 -0800 Subject: [PATCH] generate markdown --- imports.md | 81 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 21 deletions(-) diff --git a/imports.md b/imports.md index a0210f0..78acb2f 100644 --- a/imports.md +++ b/imports.md @@ -2,20 +2,34 @@ -

Import interface wasi:io/error@0.2.0-rc-2023-11-10

+

Import interface wasi:io/error@0.2.0

Types

resource error

-
+

A resource which represents some error information.

+

The only method provided by this resource is to-debug-string, +which provides some human-readable information about the error.

+

In the wasi:io package, this resource is returned through the +wasi:io/streams/stream-error type.

+

To provide more specific error information, other interfaces may +provide functions to further "downcast" this error into more specific +error information. For example, errors returned in streams derived +from filesystem types to be described using the filesystem's own +error-code type, using the function +wasi:filesystem/types/filesystem-error-code, which takes a parameter +borrow<error> and returns +option<wasi:filesystem/types/error-code>.

+

The set of functions which can "downcast" an error into a more +concrete type is open.

Functions

[method]error.to-debug-string: func

Returns a string that is suitable to assist humans in debugging @@ -32,13 +46,13 @@ hazard.

-

Import interface wasi:io/poll@0.2.0-rc-2023-11-10

+

Import interface wasi:io/poll@0.2.0

A poll API intended to let users wait for I/O events on multiple handles at once.

Types

resource pollable

-
+

pollable represents a single I/O event which may be ready, or not.

Functions

[method]pollable.ready: func

Return the readiness of a pollable. This function never blocks.

@@ -82,7 +96,7 @@ being reaedy for I/O.

-

Import interface wasi:io/streams@0.2.0-rc-2023-11-10

+

Import interface wasi:io/streams@0.2.0

WASI I/O is an I/O abstraction API which is currently focused on providing stream types.

In the future, the component model is expected to add built-in stream types; @@ -112,11 +126,28 @@ future operations.

resource input-stream

+

An input bytestream.

+

input-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use the subscribe function to obtain a pollable which can be polled +for using wasi:io/poll.

resource output-stream

-
+

An output bytestream.

+

output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe function to obtain a pollable which can be +polled for using wasi:io/poll.

Functions

[method]input-stream.read: func

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 @@ -212,6 +243,11 @@ error.

[method]output-stream.write: func

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 @@ -234,7 +270,7 @@ following pseudo-code:

let pollable = this.subscribe();
 while !contents.is_empty() {
   // Wait for the stream to become writable
-  poll-one(pollable);
+  pollable.block();
   let Ok(n) = this.check-write(); // eliding error handling
   let len = min(n, contents.len());
   let (chunk, rest) = contents.split_at(len);
@@ -243,7 +279,7 @@ while !contents.is_empty() {
 }
 this.flush();
 // Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
 // Check for any errors that arose during `flush`
 let _ = this.check-write();         // eliding error handling
@@ -303,7 +339,7 @@ all derived pollables created with this fun

[method]output-stream.write-zeroes: func

Write zeroes to a stream.

-

this should be used precisely like write with the exact same +

This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.

@@ -326,7 +362,7 @@ the following pseudo-code:

let pollable = this.subscribe();
 while num_zeroes != 0 {
   // Wait for the stream to become writable
-  poll-one(pollable);
+  pollable.block();
   let Ok(n) = this.check-write(); // eliding error handling
   let len = min(n, num_zeroes);
   this.write-zeroes(len);         // eliding error handling
@@ -334,7 +370,7 @@ while num_zeroes != 0 {
 }
 this.flush();
 // Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
 // Check for any errors that arose during `flush`
 let _ = this.check-write();         // eliding error handling
@@ -385,7 +421,7 @@ is ready for reading, before performing the splice.

-

Import interface wasi:clocks/wall-clock@0.2.0-rc-2023-11-10

+

Import interface wasi:clocks/wall-clock@0.2.0

WASI Wall Clock is a clock API intended to let users query the current time. The name "wall" makes an analogy to a "clock on the wall", which is not necessarily monotonic as it may be reset.

@@ -426,7 +462,7 @@ also known as Unix Time.
  • datetime
    • -

    Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10

    +

    Import interface wasi:filesystem/types@0.2.0

    WASI filesystem is a filesystem API primarily intended to let users run WASI programs that access their files on their existing filesystems, without significant overhead.

    @@ -856,8 +892,11 @@ not reuse it thereafter.

    resource descriptor

    +

    A descriptor is a reference to a filesystem object, which may be a file, +directory, named pipe, special file, or other object on which filesystem +calls may be made.

    resource directory-entry-stream

    -
    +

    A stream of directory entries.

    Functions

    [method]descriptor.read-via-stream: func

    Return a stream for reading from a file, if available.

    @@ -1303,7 +1342,7 @@ errors are filesystem-related errors.

    -

    Import interface wasi:filesystem/preopens@0.2.0-rc-2023-11-10

    +

    Import interface wasi:filesystem/preopens@0.2.0

    Types

    type descriptor