Add beginnings of a Resources and Handles design document. #319
Conversation
monoclex
changed the title
design/file-descriptors.md
Outdated
| ``` | ||
|
|
||
| # Files | ||
| Files can be opened and closed with the method [`path_open`](https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md#-path_openfd-fd-dirflags-lookupflags-path-string-oflags-oflags-fs_rights_base-rights-fs_rights_inherting-rights-fdflags-fdflags---errno-fd), and simply drop the returned `fd` to close it. These commands will fail if the WASM environment did not give the program permission to execute these. |
There was a problem hiding this comment.
This seems to be too specific for a design document as it refers to a specific snapshot and will easily get out of sync.
There was a problem hiding this comment.
Would modifying the URL to a less precise URL fix this? If not, does the document have a better fit elsewhere?
There was a problem hiding this comment.
How about documenting them in the witx files, which are the sources from which the docs.md files are generated?
There was a problem hiding this comment.
Where are the witx files? Sorry if this is obvious and I'm just missing it.
There was a problem hiding this comment.
Currently they live here: https://github.com/WebAssembly/WASI/tree/master/phases/ephemeral/witx
We'll likely be reorganizing things as WASI modularization moves forward, but this is where they are for now.
There was a problem hiding this comment.
I apologize for being slow here! This is a great topic to start documenting, as I agree, file descriptors are one of the most important concepts we have. This document looks like a good start -- I expect a lot of things will evolve over time, but it's useful to start somewhere! -- I just have a few review comments below:
|
This looks like it's in good shape. I see it's still marked as a "Draft"; is there more to be done here? |
|
Ah yeah, I was going to move the documentation for specific code related to files to the WITX documentation, then link to it in the |
monoclex
force-pushed
the
file-descriptors-information
branch
from
8878a93 to
7a71315
Compare
|
Apologies for it having been a while since I've worked on this (so much for "relatively soon", eh?). I recall last stating that I needed to do this,
but can't quite seem to remember what that would entail (I'm unsure what I would link to in the |
This comment has been minimized.
This comment has been minimized.
|
Thanks for picking this up again! Since this PR was started, a few developments have changed the landscape somewhat: A major development since this PR was started has been the development of handles as an explicit feature of the interface-types proposal. The canonical ABI PR includes an ABI which can represent handles as And, WASI is moving toward modularization. Stdout, stdin, stderr are interesting. These won't be needed in all use cases, so I expect WASI will move toward a model where those will be defined by libc and tooling rather than by WASI itself. That said, we'll likely need to continue to support "commands" in their current form, which expect 0, 1, and 2 to be prepopulated. This isn't all figured out yet, but I'm starting to think of wasi-classic-command as the place where we'll collect documentation for how these kinds of commands work. Does that make sense? |
|
Thanks for the information! I read more into what you mentioned, by reading the Handle and Resources presentation, the Scoping and Layering presentation, and through the canonical ABI proposal that was linked. I decided to make this PR more geared towards resources and handles, as that seems like the replacement for file descriptors, and tried to write documentation for them based on my current understanding. I ended up dropping the mention to the console, but I should probably put that back in there if the commands proposal makes use of resources and handles. |
monoclex
changed the title
|
As another update here, interface types has now evolved into a component model, which is now defining the concepts of handles, resources, and commands. Going forward, the component model will be the best place for documentation about what handles and resources are and how they work, with the WASI repo here focusing more on just the APIs that are built on top of them. |
|
As I mentioned above, resources and handles are now defined by the component model. |
File Descriptors seem like they will be a very ubiquitous concept in WASI, thus guiding users to understand them would be extremely helpful. As the implementation is still not fully fleshed out and very much a draft, this document is to remain very incomplete but ideally would have examples and links to other documents so developers can figure out how to use these APIs. This is to resolve another part of #316