Add beginnings of a Resources and Handles design document.

[monoclex]

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

[sunfishcode]

This looks like it's in good shape. I see it's still marked as a "Draft"; is there more to be done here?

[monoclex]

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 Files header. Haven't gotten around to that yet, my bad - I'll try get it done relatively soon.

[monoclex]

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,

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 Files header. Haven't gotten around to that yet, my bad - I'll try get it done relatively soon.

but can't quite seem to remember what that would entail (I'm unsure what I would link to in the Files section, where in the witx folder I would link to that section, and what code I would move over). Moreover, I assume there might be significant changes since I've last worked on this, so perhaps it'd be best to get another look at it.

[programmerjake]

perhaps there should be some description added of how a file descriptor is closed, since just dropping an integer does nothing.

[sunfishcode]

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 i32 indices within modules, and includes resource lifetimes and closing handles. I expect we'll want to rebase WASI's concept of file descriptors on this new handle mechanism. That will let WASI focus on API functionality, and leave low-level resource management to lower levels of the stack that all APIs can use.

And, WASI is moving toward modularization. path_open is now defined in the wasi-filesystem proposal. I think that's the best place for documenting how to open and close files now.

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?

[monoclex]

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.

[sunfishcode]

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.

[sunfishcode]

As I mentioned above, resources and handles are now defined by the component model.