Add an option to use the new I/O safety types and traits in std.

I/O safety is now [in Rust Nightly]; add a mode to io-lifetimes to use
std's types and traits. See the blurb in README.md for more details.

[in Rust Nightly]: rust-lang/rust#87329

Author: sunfishcode

.github/workflows/main.yml

@@ -47,3 +47,30 @@ jobs:
       with:
         toolchain: ${{ matrix.rust }}
     - run: cargo test --workspace --all-features
+
+  test_use_std:
+    name: Test with std's types and traits
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        build: [ubuntu-nightly, windows-nightly]
+        include:
+          - build: ubuntu-nightly
+            os: ubuntu-latest
+            rust: nightly
+          - build: windows-nightly
+            os: windows-latest
+            rust: nightly
+
+    env:
+      RUSTFLAGS: --cfg io_lifetimes_use_std
+      RUSTDOCFLAGS: --cfg io_lifetimes_use_std
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: true
+    - uses: ./.github/actions/install-rust
+      with:
+        toolchain: ${{ matrix.rust }}
+    - run: cargo test --workspace --all-features

README.md

@@ -99,6 +99,36 @@ is what motivates having `BorrowedFd` instead of just using `&OwnedFd`.
 Note the use of `Option<OwnedFd>` as the return value of `open`, representing
 the fact that it can either succeed or fail.
 
+## I/O Safety in Rust Nightly
+
+The I/O Safety
+[implementation PR](https://github.com/rust-lang/rust/pull/87329) has now
+landed and is available on Rust Nightly. It can be used directly, or through
+io-lifetimes: when `io_lifetimes_use_std` mode is enabled, io-lifetimes uses
+the std's `OwnedFd`, `BorrowedFd`, and `AsFd` instead of defining its own.
+
+To enable `io_lifetimes_use_std` mode:
+  - Set the environment variable `RUSTFLAGS=--cfg=io_lifetimes_use_std`, and
+  - add `#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]` to your
+    lib.rs or main.rs.
+
+The code in `std` uses `From<OwnedFd>` and `Into<OwnedFd>` instead of `FromFd`
+and `IntoFd`. io-lifetimes is unable to provide impls for these for third-party
+types, so it continues to provide `FromFd` and `IntoFd` for now, with default
+impls that forward to `From<OwnedFd>` and `Into<OwnedFd>` in
+`io_lifetimes_use_std` mode.
+
+io-lifetimes also includes several features which are not (yet?) in std,
+including the portability traits `AsFilelike`/`AsSocketlike`/etc., the
+`from_into_*` functions in the `From*` traits, and [views].
+
+If you test a crate with the std I/O safety types and traits, or io-lifetimes
+in `io_lifetimes_use_std` mode, please post a note about it in the
+[I/O safety tracking issue] as an example of usage.
+
+[I/O safety tracking issue]: https://github.com/rust-lang/rust/issues/87074
+[views]: https://docs.rs/io-lifetimes/*/io_lifetimes/views/index.html
+
 ## Prior Art
 
 There are several similar crates: [fd](https://crates.io/crates/fd),

examples/easy-conversions.rs

@@ -2,6 +2,8 @@
 //! implementing `IntoFilelike` and `FromSocketlike` to types implementing
 //! `FromFilelike` and `IntoSocketlike`, respectively.
 
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
+
 use io_lifetimes::FromFilelike;
 use std::fs::File;
 use std::io::{self, Read};

examples/flexible-apis.rs

@@ -4,6 +4,8 @@
 //! The following uses the POSIX-ish `Fd` types; similar considerations
 //! apply to the Windows and portable types.
 
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
+
 #[cfg(all(feature = "close", not(windows)))]
 use io_lifetimes::{AsFd, BorrowedFd, IntoFd, OwnedFd};
 

examples/hello.rs

@@ -2,6 +2,7 @@
 //! the io-lifetimes API.
 
 #![cfg_attr(not(rustc_attrs), allow(unused_imports))]
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
 
 #[cfg(feature = "close")]
 use io_lifetimes::example_ffi::*;

examples/owning-wrapper.rs

@@ -1,5 +1,7 @@
 //! A simple example implementing the main traits for a type.
 
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
+
 use io_lifetimes::OwnedFilelike;
 #[cfg(not(windows))]
 use io_lifetimes::{AsFd, BorrowedFd, FromFd, IntoFd, OwnedFd};

examples/portable-views.rs

@@ -1,6 +1,8 @@
 //! io-lifetimes provides safe, convenient, and portable ways to temporarily
 //! view an I/O resource as a `File`, `Socket`, or other types.
 
+#![cfg_attr(io_lifetimes_use_std, feature(io_safety))]
+
 use io_lifetimes::AsFilelike;
 use std::fs::File;
 use std::io::{self, stdout};