bytecodealliance / bytecodealliance/rustix
Document and stablize functions from `rustix::runtime`.
- Dominant language
- Rust
- Stars
- 2.1k
- Forks
- 294
- Avg merge
- 4h 7m
- Merged PRs (30d)
- 2
Description
We should work towards moving functions currently in `rustix::runtime` out into the public API modules. This should involve thinking about their safety conditions, and figuring out what kind of public API works for the expected use cases. Also, `rustix::runtime` is not currently implemented for the libc backend, and it's desirable for rustix to expos the same features across its two backends, so that users (including indirect users) have the choice of whether to use the libc backend.
For example, `rustix::runtime::sigaction` exposes kernel-level signal registration function that bypasses libc. Libc implementations don't expect this to ever happen, so doing so may invoke undefined behavior. The precise conditions aren't documented, and could change with libc versions. As far as I can tell, the only guidance we could give for some functions would be "don't ever call this in a process which also contains a libc, or anything acting like a libc, including [origin](https://docs.rs/origin)". And that's in addition to regular safety conditions, such as that the various raw pointers have to be used properly, and that don't `SIGSEGV` and `SIGBUS` shouldn't be ignored, because it could potentially bypass stack overflow guards, and all the safety considerations around signal handlers, and probably more.
In general, the main options for any given function in `rustix::runtime` include:
- Make it public in rustix, with sufficiently imposing documentation, and either add a libc backend implementation using `libc::syscall` (if it's not incompatible with libc), or add further documentation saying "using this will prevent your users from enabling rustix's libc backed; please consider what you do here" or so, or
- Have rustix expose a higher-level or more specialized API for it.
- Expose it through origin instead of rustix (eg. [`origin::signal::sigaction`](https://docs.rs/origin/latest/origin/signal/fn.sigaction.html)).
Which of these three is best for any given function depends on what kinds of use cases people will have. So for any function in `rustix::runtime` that anyone would like to see documented and stabilized, please comment about it here, and describe your use case!
Contributor guide
Assessment
This issue has not been assessed yet.