{"id":15401088,"url":"https://github.com/sunfishcode/io-lifetimes","last_synced_at":"2025-05-15T09:04:18.231Z","repository":{"id":37830153,"uuid":"372098119","full_name":"sunfishcode/io-lifetimes","owner":"sunfishcode","description":"A low-level I/O ownership and borrowing library","archived":false,"fork":false,"pushed_at":"2024-12-04T01:31:09.000Z","size":246,"stargazers_count":100,"open_issues_count":1,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T04:09:19.539Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sunfishcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-30T01:10:44.000Z","updated_at":"2025-03-30T00:48:07.000Z","dependencies_parsed_at":"2023-12-01T01:28:53.350Z","dependency_job_id":"caf30c1b-6a4a-4f18-9ccc-12f571a9f857","html_url":"https://github.com/sunfishcode/io-lifetimes","commit_stats":{"total_commits":234,"total_committers":6,"mean_commits":39.0,"dds":0.02991452991452992,"last_synced_commit":"893a39ff6d84dc7d5fa9a03e26f8605cbeaea2ee"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fio-lifetimes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fio-lifetimes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fio-lifetimes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sunfishcode%2Fio-lifetimes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sunfishcode","download_url":"https://codeload.github.com/sunfishcode/io-lifetimes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166865,"owners_count":21058481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T15:56:27.319Z","updated_at":"2025-04-10T06:20:16.504Z","avatar_url":"https://github.com/sunfishcode.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u003ccode\u003eio-lifetimes\u003c/code\u003e\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003cstrong\u003eA low-level I/O ownership and borrowing library\u003c/strong\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/sunfishcode/io-lifetimes/actions?query=workflow%3ACI\"\u003e\u003cimg src=\"https://github.com/sunfishcode/io-lifetimes/workflows/CI/badge.svg\" alt=\"Github Actions CI Status\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://crates.io/crates/io-lifetimes\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/io-lifetimes.svg\" alt=\"crates.io page\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://docs.rs/io-lifetimes\"\u003e\u003cimg src=\"https://docs.rs/io-lifetimes/badge.svg\" alt=\"docs.rs docs\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nThis library introduces `OwnedFd`, `BorrowedFd`, and supporting types and\ntraits, and corresponding features for Windows, which implement safe owning\nand borrowing I/O lifetime patterns.\n\nThis is associated with [RFC 3128], the I/O Safety RFC, which is now merged.\nWork is now underway to move the `OwnedFd` and `BorrowedFd` types and `AsFd`\ntrait developed here into `std`.\n\nFor a quick taste, check out the code examples:\n\n - [hello], a basic demo of this API, doing low-level I/O manually, using the\n   [provided example FFI bindings]\n - [easy-conversions], demonstrating the `from_into` convenience feature for\n   converting from an `impl Into*` into an `impl From*`.\n - [portable-views], demonstrating the convenience feature which allows one\n   to temporarily \"view\" a file descriptor as any owning type such as `File`\n - [flexible-apis], demonstrating how to write library APIs that accept\n   untyped I/O resources.\n - [owning-wrapper], demonstrating how to implement a type which wraps an\n   `Owned*` type.\n\n[hello]: https://github.com/sunfishcode/io-lifetimes/blob/main/examples/hello.rs\n[easy-conversions]: https://github.com/sunfishcode/io-lifetimes/blob/main/examples/easy-conversions.rs\n[portable-views]: https://github.com/sunfishcode/io-lifetimes/blob/main/examples/portable-views.rs\n[flexible-apis]: https://github.com/sunfishcode/io-lifetimes/blob/main/examples/flexible-apis.rs\n[owning-wrapper]: https://github.com/sunfishcode/io-lifetimes/blob/main/examples/owning-wrapper.rs\n[provided example FFI bindings]: https://github.com/sunfishcode/io-lifetimes/blob/main/src/example_ffi.rs\n\nThe core of the API is very simple, and consists of two main types and three\nmain traits:\n\n```rust\npub struct BorrowedFd\u003c'fd\u003e { ... }\npub struct OwnedFd { ... }\n\npub trait AsFd { ... }\npub trait IntoFd { ... }\npub trait FromFd { ... }\n\nimpl AsRawFd for BorrowedFd\u003c'_\u003e { ... }\nimpl AsRawFd for OwnedFd { ... }\nimpl IntoRawFd for OwnedFd { ... }\nimpl FromRawFd for OwnedFd { ... }\n\nimpl Drop for OwnedFd { ... }\n\nimpl AsFd for BorrowedFd\u003c'_\u003e { ... }\nimpl AsFd for OwnedFd { ... }\nimpl IntoFd for OwnedFd { ... }\nimpl FromFd for OwnedFd { ... }\n```\n\nOn Windows, there are `Handle` and `Socket` versions of every `Fd` thing, and\na special `HandleOrInvalid` type to cope with inconsistent error reporting\nin the Windows API.\n\n## The magic of transparency\n\nHere's the fun part. `BorrowedFd` and `OwnedFd` are `repr(transparent)` and\nhold `RawFd` values, and `Option\u003cBorrowedFd\u003e` and `Option\u003cOwnedFd\u003e` are\nFFI-safe (on Rust \u003e= 1.63), so they can all be used in FFI [directly]:\n\n[directly]: https://github.com/sunfishcode/io-lifetimes/blob/main/src/example_ffi.rs\n\n```rust\nextern \"C\" {\n    pub fn open(pathname: *const c_char, flags: c_int, ...) -\u003e Option\u003cOwnedFd\u003e;\n    pub fn read(fd: BorrowedFd\u003c'_\u003e, ptr: *mut c_void, size: size_t) -\u003e ssize_t;\n    pub fn write(fd: BorrowedFd\u003c'_\u003e, ptr: *const c_void, size: size_t) -\u003e ssize_t;\n    pub fn close(fd: OwnedFd) -\u003e c_int;\n}\n```\n\nWith bindings like this, users never have to touch `RawFd` values. Of course,\nnot all code will do this, but it is a fun feature for code that can. This\nis what motivates having `BorrowedFd` instead of just using `\u0026OwnedFd`.\n\nNote the use of `Option\u003cOwnedFd\u003e` as the return value of `open`, representing\nthe fact that it can either succeed or fail.\n\n## I/O Safety in Rust\n\nI/O Safety feature is stablized in Rust 1.63. With this version or later,\nio-lifetimes will use and re-export the standard-library types and traits. With\nolder versions, io-lifetimes defines its own copy of these types and traits.\n\nio-lifetimes also includes several features which are not (yet?) in std,\nincluding the portability traits `AsFilelike`/`AsSocketlike`/etc., the\n`from_into_*` functions in the `From*` traits, and [views].\n\n[views]: https://docs.rs/io-lifetimes/*/io_lifetimes/views/index.html\n\n## Prior Art\n\nThere are several similar crates: [fd](https://crates.io/crates/fd),\n[filedesc](https://crates.io/crates/filedesc),\n[filedescriptor](https://crates.io/crates/filedescriptor),\n[owned-fd](https://crates.io/crates/owned-fd), and\n[unsafe-io](https://crates.io/crates/unsafe-io).\n\nSome of these provide additional features such as the ability to create pipes\nor sockets, to get and set flags, and to do read and write operations.\nio-lifetimes omits these features, leaving them to to be provided as separate\nlayers on top.\n\nMost of these crates provide ways to duplicate a file descriptor. io-lifetimes\ncurrently treats this as another feature that can be provided by a layer on\ntop, though if there are use cases where this is a common operation, it could\nbe added.\n\nio-lifetimes's distinguishing features are its use of `repr(transparent)`\nto support direct FFI usage, niche optimizations so `Option` can support direct\nFFI usafe as well (on Rust \u003e= 1.63), lifetime-aware `As*`/`Into*`/`From*`\ntraits which leverage Rust's lifetime system and allow safe and checked\n`from_*` and `as_*`/`into_*` functions, and powerful convenience features\nenabled by its underlying safety.\n\nio-lifetimes also has full Windows support, as well as Unix/Windows\nportability abstractions, covering both file-like and socket-like types.\n\nio-lifetimes's [`OwnedFd`] type is similar to\n[fd](https://crates.io/crates/fd)'s\n[`FileDesc`](https://docs.rs/fd/0.2.3/fd/struct.FileDesc.html). io-lifetimes\ndoesn't have a `close_on_drop` parameter, and instead uses [`OwnedFd`] and\n[`BorrowedFd`] to represent dropping and non-dropping handles, respectively, in\na way that is checked at compile time rather than runtime.\n\nio-lifetimes's [`OwnedFd`] type is also similar to\n[filedesc](https://crates.io/crates/filedesc)'s\n[`FileDesc`](https://docs.rs/filedesc/0.3.0/filedesc/struct.FileDesc.html)\nio-lifetimes's `OwnedFd` reserves the value -1, so it doesn't need to test for\n`-1` in its `Drop`, and `Option\u003cOwnedFd\u003e` (on Rust \u003e= 1.63) is the same size\nas `FileDesc`.\n\nio-lifetimes's [`OwnedFd`] type is also similar to\n[owned-fd](https://crates.io/crates/owned-fd)'s\n[`OwnedFd`](https://docs.rs/owned-fd/0.1.0/owned_fd/struct.OwnedFd.html).\nio-lifetimes doesn't implement `Clone`, because duplicating a file descriptor\ncan fail due to OS process limits, while `Clone` is an infallible interface.\n\nio-lifetimes's [`BorrowedFd`] is similar to\n[owned-fd](https://crates.io/crates/owned-fd)'s\n[`FdRef`](https://docs.rs/owned-fd/0.1.0/owned_fd/struct.FdRef.html), except it\nuses a lifetime parameter and `PhantomData` rather than transmuting a raw file\ndescriptor value into a reference value.\n\nio-lifetimes's convenience features are similar to those of\n[unsafe-io](https://crates.io/crates/unsafe-io), but io-lifetimes is built on\nits own `As*`/`Into*`/`From*` traits, rather than extending\n`AsRaw*`/`IntoRaw*`/`FromRaw*` with\n[`OwnsRaw`](https://docs.rs/unsafe-io/0.6.9/unsafe_io/trait.OwnsRaw.html), so\nthey're simpler and safer to use. io-lifetimes doesn't include unsafe-io's\n`*ReadWrite*` or `*HandleOrSocket*` abstractions, and leaves these as features\nto be provided by separate layers on top.\n\n## Minimum Supported Rust Version (MSRV)\n\nThis crate currently works on the version of [Rust on Debian stable], which is\ncurrently Rust 1.63. This policy may change in the future, in minor version\nreleases, so users using a fixed version of Rust should pin to a specific\nversion of this crate.\n\n[`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html\n[`BorrowedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.BorrowedFd.html\n[RFC 3128]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunfishcode%2Fio-lifetimes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsunfishcode%2Fio-lifetimes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsunfishcode%2Fio-lifetimes/lists"}