50 releases (15 stable)
2.0.3 | Dec 1, 2023 |
---|---|
2.0.2 | Jun 30, 2023 |
1.1.0-pre.0 | May 24, 2023 |
1.0.9 | Mar 20, 2023 |
0.2.0 | Jun 24, 2021 |
#13 in Operating systems
2,696,184 downloads per month
Used in 1,742 crates
(25 directly)
63KB
805 lines
This library introduces OwnedFd
, BorrowedFd
, and supporting types and
traits, and corresponding features for Windows, which implement safe owning
and borrowing I/O lifetime patterns.
This is associated with RFC 3128, the I/O Safety RFC, which is now merged.
Work is now underway to move the OwnedFd
and BorrowedFd
types and AsFd
trait developed here into std
.
For a quick taste, check out the code examples:
- hello, a basic demo of this API, doing low-level I/O manually, using the provided example FFI bindings
- easy-conversions, demonstrating the
from_into
convenience feature for converting from animpl Into*
into animpl From*
. - portable-views, demonstrating the convenience feature which allows one
to temporarily "view" a file descriptor as any owning type such as
File
- flexible-apis, demonstrating how to write library APIs that accept untyped I/O resources.
- owning-wrapper, demonstrating how to implement a type which wraps an
Owned*
type.
The core of the API is very simple, and consists of two main types and three main traits:
pub struct BorrowedFd<'fd> { ... }
pub struct OwnedFd { ... }
pub trait AsFd { ... }
pub trait IntoFd { ... }
pub trait FromFd { ... }
impl AsRawFd for BorrowedFd<'_> { ... }
impl AsRawFd for OwnedFd { ... }
impl IntoRawFd for OwnedFd { ... }
impl FromRawFd for OwnedFd { ... }
impl Drop for OwnedFd { ... }
impl AsFd for BorrowedFd<'_> { ... }
impl AsFd for OwnedFd { ... }
impl IntoFd for OwnedFd { ... }
impl FromFd for OwnedFd { ... }
On Windows, there are Handle
and Socket
versions of every Fd
thing, and
a special HandleOrInvalid
type to cope with inconsistent error reporting
in the Windows API.
The magic of transparency
Here's the fun part. BorrowedFd
and OwnedFd
are repr(transparent)
and
hold RawFd
values, and Option<BorrowedFd>
and Option<OwnedFd>
are
FFI-safe (on Rust >= 1.63), so they can all be used in FFI directly:
extern "C" {
pub fn open(pathname: *const c_char, flags: c_int, ...) -> Option<OwnedFd>;
pub fn read(fd: BorrowedFd<'_>, ptr: *mut c_void, size: size_t) -> ssize_t;
pub fn write(fd: BorrowedFd<'_>, ptr: *const c_void, size: size_t) -> ssize_t;
pub fn close(fd: OwnedFd) -> c_int;
}
With bindings like this, users never have to touch RawFd
values. Of course,
not all code will do this, but it is a fun feature for code that can. This
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
I/O Safety feature is stablized in Rust 1.63. With this version or later, io-lifetimes will use and re-export the standard-library types and traits. With older versions, io-lifetimes defines its own copy of these types and traits.
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.
Prior Art
There are several similar crates: fd, filedesc, filedescriptor, owned-fd, and unsafe-io.
Some of these provide additional features such as the ability to create pipes or sockets, to get and set flags, and to do read and write operations. io-lifetimes omits these features, leaving them to to be provided as separate layers on top.
Most of these crates provide ways to duplicate a file descriptor. io-lifetimes currently treats this as another feature that can be provided by a layer on top, though if there are use cases where this is a common operation, it could be added.
io-lifetimes's distinguishing features are its use of repr(transparent)
to support direct FFI usage, niche optimizations so Option
can support direct
FFI usafe as well (on Rust >= 1.63), lifetime-aware As*
/Into*
/From*
traits which leverage Rust's lifetime system and allow safe and checked
from_*
and as_*
/into_*
functions, and powerful convenience features
enabled by its underlying safety.
io-lifetimes also has full Windows support, as well as Unix/Windows portability abstractions, covering both file-like and socket-like types.
io-lifetimes's OwnedFd
type is similar to
fd's
FileDesc
. io-lifetimes
doesn't have a close_on_drop
parameter, and instead uses OwnedFd
and
BorrowedFd
to represent dropping and non-dropping handles, respectively, in
a way that is checked at compile time rather than runtime.
io-lifetimes's OwnedFd
type is also similar to
filedesc's
FileDesc
io-lifetimes's OwnedFd
reserves the value -1, so it doesn't need to test for
-1
in its Drop
, and Option<OwnedFd>
(on Rust >= 1.63) is the same size
as FileDesc
.
io-lifetimes's OwnedFd
type is also similar to
owned-fd's
OwnedFd
.
io-lifetimes doesn't implement Clone
, because duplicating a file descriptor
can fail due to OS process limits, while Clone
is an infallible interface.
io-lifetimes's BorrowedFd
is similar to
owned-fd's
FdRef
, except it
uses a lifetime parameter and PhantomData
rather than transmuting a raw file
descriptor value into a reference value.
io-lifetimes's convenience features are similar to those of
unsafe-io, but io-lifetimes is built on
its own As*
/Into*
/From*
traits, rather than extending
AsRaw*
/IntoRaw*
/FromRaw*
with
OwnsRaw
, so
they're simpler and safer to use. io-lifetimes doesn't include unsafe-io's
*ReadWrite*
or *HandleOrSocket*
abstractions, and leaves these as features
to be provided by separate layers on top.
Minimum Supported Rust Version (MSRV)
This crate currently works on the version of [Rust on Debian stable], which is currently Rust 1.63. This policy may change in the future, in minor version releases, so users using a fixed version of Rust should pin to a specific version of this crate.
Dependencies
~0–11MB
~136K SLoC