1.0 release planning

[sunfishcode]

Here's a planning issue for a 1.0 release, similar to the one for the 0.38 release. Hopefully we won't need a semver bump for a good long while, but when we do, here's the list of changes we can make:

• Remove the deprecated mount functions in the fs module (details)
• Make the underlying type of rustix::fs::Access consistent between linux_raw and libc backends (Port 1.0-staging to main #1152)
• Rename mount_recursive_bind to mount_bind_recursive? Factor out a new top-level mount module. #763 (comment) (Rename mount_recursive_bind to mount_bind_recursive. #1273)
• Change SeekFrom::Hole and SeekFrom::Data's field from i64 to u64. (Make the offsets for SeekFrom's Hole and Data unsigned. #1266)
• rename Shutdown::ReadWrite to Shutdown::Both to align with std (Rename Shutdown::ReadWrite to Shutdown::Both. #1264)
• remove the features = ["extra_traits"] from the libc dependency (Remove the "libc-extra-traits" feature. #1168)
• move (or perhaps alias?) sched_yield and other sched_* functions from process to thread, since they apply to threads rather than processes on Linux etc. (Move sched_* and membarrier_* into rustix::thread. #1265)
• stx_mtime and similar members of Statx should be i64, because Unix timestamps can be negative.
• futex's first argument should be Atomic
• Remove get_ from sockopt getters, following Rust convention. Consider removing get_ in other things too. (Rename sockopts getters to remove the "get_". #1269)
• The udata argument to rustix::event::kqueue::Event::new should be a pointer instead of an isize in order to better preserve provenance. (Make APIs preserve strict provenance. #1270)
• The stx_attributes_mask field of Statx with flags like libc::STATX_ATTR_MOUNT_ROOT should ideally be a bitflags, which requires making Statx a custom type (which should match layout with libc::statx). (Reorganize Stat, Statx, and SockaddrStorage #1282)
• Rename get_* functions (eg. sockopts) to remove the get_ prefix, which is more idiomatic Rust?
• Rename MountPropagationFlags::SLAVE (Rename a flag in MountPropagationFlags. #1169)
• Rename some of WaitidOptions, WaitidStatus, and/or WaitId to make the capitalization of Id consistent (Rename Waidid* to WaidId*, for consistency with WaitId. #1267)
• Remove the inotify_ prefixes from things in the fs::inotify module.
• Remove the shm_ and Shm prefixes from things in the shm module.
• Figure out a way to do a recv into an uninitialized buffer with the TRUNC flag set (see Fix recv_uninit to handle the TRUNC flag. #1159) (Report the number of received bytes in recv_uninit and recvfrom_uninit. #1278)
• remove rustix::procfs and publish rustix-linux-procfs as the replacement (Remove procfs. #1275)
• remove linux-raw-sys from the public API (Port 1.0-staging to main #1152) (Remove most linux-raw-sys types from the public API #1277) (Reorganize Stat, Statx, and SockaddrStorage #1282)
• change io_uring_register_files_skip from a const fn to a constant. (Replace the io_uring_register_files_skip function with a constant. #1268)

Deferring for now:

• move rustix::thread sleep functions into a new rustix::sleep module, because they're usable from single-threaded programs too
• Move Dir into its own crate, and have rustix export getdents directly?
• Split open and openat into separate functions for "create" which needs a mode vs. "open existing" which doesn't need a mode?
• Make RecvAncillaryBuffer::drain always remove all messages, even if the iterator isn't exhausted. With that, we can remove the read_and_length in AncillaryDrain.
• Replace rustix::cstr! with something like rustix::nativestr! so that users don't hard code "native strings are C strings" in their code?
• rename Arg::as_str to avoid "a method with this name may be added to the standard library in the future" warnings
• rustix::process::waitpid has no way to wait for specific process groups (Pid now requires non-negative values). waitpgid has been added as a temporary workaround.
• remove libc from the public API (Port 1.0-staging to main #1152) (Remove most linux-raw-sys types from the public API #1277)

Don't do these:

• set_ip_add_membership/get_ip_add_membership should take address and ifindex arguments and *_with_ifindex should be removed.
• Rename ClockId::Uptime on FreeBSD to Boottime, since it's an alias

[notgull]

If this is going to be a stable release, we should make sure that libc and linux-raw-sys aren't exposed in the public API. I know there are still a few places where it is.

In my opinion a stable release is a bad idea, as the API is still somewhat volatile. There should at least be an "unstable" feature flag to test new APIs for inclusion, like Tokio has.

[sunfishcode]

I already consider 0.38 to be stable. For example, I maintain an older version of linux-raw-sys to preserve compatibility with rustix 0.38. And I'm not aware of any significant volatility in the 0.38 API. It's added lots of features, and even deprecated a handful of things, but ideas for breaking changes are collected here in this issue, specifically to keep 0.38 stable.

So my idea for 1.0 is just to better communicate what's already happening.

It would be nice to better encapsulate libc/linux-raw-sys types, and I'm open to adding an "unstable" feature flag if there's a need for it. I'm under the impression that these aren't urgent right now, though I'd be happy to learn more about how these impact users.

[SUPERCILEX]

I'd like to propose making the timeout param in https://docs.rs/rustix/latest/rustix/event/fn.poll.html be an Option<u32> where None passes -1 to act as an infinite timeout. That feels like a clearer interface than anything negative is infinity.

[SUPERCILEX]

From #1110 (comment):
epoll appears to be inconsistent in that it expects users to use the module prefix (i.e. epoll::foo) instead of using the free function directly. This is neat, but it's inconsistent with the rest of rustix's APIs: inotify, port, eventfd, io_uring, mount, shm, and probably others I didn't have time to look at. @sunfishcode thoughts on a PR that restores the epoll_ prefix with some deprecations? We could go the other direction, but that interacts poorly with auto-complete and would be much more breaking so not worth it IMO.

Sidenote: the deprecations won't actually work due to rust-lang/rust#30827. (For example the fs::*mount APIs are deprecated but there's no warning about it.)

[sunfishcode]

All todo items here are now either fixed, have posted PRs, or are tentatively recategorized to "Defering for now". I'll give these some time, while I work on documenting the changes in CHANGELOG.md and do extra testing and tidying, but the end is now in sight.

From #1105 (comment), let's add to the todo list that we need to fix the occurrences of cargo clippy --workspace --all-targets --features all-apis -- -Aclippy::all -Dclippy::impl_trait_in_params (and use-libc).

A PR doing this for all public APIs is posted at #1283.

From #1110 (comment): epoll appears to be inconsistent in that it expects users to use the module prefix (i.e. epoll::foo) instead of using the free function directly. This is neat, but it's inconsistent with the rest of rustix's APIs: inotify, port, eventfd, io_uring, mount, shm, and probably others I didn't have time to look at. @sunfishcode thoughts on a PR that restores the epoll_ prefix with some deprecations? We could go the other direction, but that interacts poorly with auto-complete and would be much more breaking so not worth it IMO.

In my experience the autocomplete is ok once one has the appropriate use of the API module in scope.

I've now filed #1284 to use this style in the port API, and I've ensured that all modules using this style have examples showing the appropriate use, and doc aliases.

eventfd is just one function and one type so I don't think it needs a pub mod. That leaves io_uring and mount, which are a little harder to fit into this style. mount::un feels weird, IoringSendFlags would clash with SendFlags without its prefix, and subjectively they don't seem to fit this style quite as well.

I'd like to propose making the timeout param in https://docs.rs/rustix/latest/rustix/event/fn.poll.html be an Option<u32> where None passes -1 to act as an infinite timeout. That feels like a clearer interface than anything negative is infinity.

I haven't yet made this change. I do like how it makes the interface clearer, but I'm unsure about the range check it introduces.

If this is going to be a stable release, we should make sure that libc and linux-raw-sys aren't exposed in the public API. I know there are still a few places where it is.

With #1152 now landed, #1277 and #1282 remove the last linux-raw-sys types from the public API.

I haven't yet removed all the libc types when using the libc backend. That would require duplicating a lot of platform-specific types like stat which gratuitously varies in all kinds of details across architectures and OS's. Perhaps just avoiding linux-raw-sys is good enough for now, because the libc crate doesn't have semver changes nearly as often.

None of this is final at this point; I'm open to feedback here.

[SUPERCILEX]

I haven't yet made this change. I do like how it makes the interface clearer, but I'm unsure about the range check it introduces.

By this do you mean that we're limiting possible inputs the caller can supply (namely no negative numbers). I feel like that's reasonable as we probably want a different API if negative numbers start meaning something else.

---

I'd really like to see the story around MaybeUninit buffers resolved for 1.0 (or a clear expectation that there will be a 2.0 addressing the issue). I'm still on team dependent types (as in the input to the function determines the return type), but I'm not sure how we should hash this out.

[sunfishcode]

I haven't yet made this change. I do like how it makes the interface clearer, but I'm unsure about the range check it introduces.

By this do you mean that we're limiting possible inputs the caller can supply (namely no negative numbers). I feel like that's reasonable as we probably want a different API if negative numbers start meaning something else.

If it's Option<u32>, then the u32's range includes values greater than poll's c_int supports. Maybe it means we should just go all the way to Option<Timespec> and use ppoll in the implementation when we can (Linux, most BSDs).

I'd really like to see the story around MaybeUninit buffers resolved for 1.0 (or a clear expectation that there will be a 2.0 addressing the issue). I'm still on team dependent types (as in the input to the function determines the return type), but I'm not sure how we should hash this out.

Is that #1108 and #1110? Thanks for the reminder; I'll take another look at those before the release.

[SUPERCILEX]

we should just go all the way to Option and use ppoll

If we can, that sounds even better!

---

Yup, mostly #1110 as I think it could have ripple effects (e.g. getting rid of io::read_uninit).