From 37d6b8f15aa9abd43212d127fdc4d6c1b9d32b6e Mon Sep 17 00:00:00 2001 From: Ryo Onodera Date: Mon, 7 Oct 2024 15:49:26 +0900 Subject: [PATCH 1/2] Improve some documentations --- README.md | 1 + enum-ptr/src/lib.rs | 8 ++++--- enum-ptr/src/traits/aligned.rs | 42 ++++++++++++++++++++++++++++++---- 3 files changed, 44 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 03ba51a..4c68a2d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ *[0.2.0 beta](https://crates.io/crates/enum-ptr/0.2.0-beta.0) is released with a lot of new features. I need feedback from community.* This crate provides a custom derive macro `EnumPtr` to generate bridges between an enum `T` and `Compact` with minimum cost. `Compact` is the compact representation of `T`, and it is only one pointer wide. +In other words, this crate is a library for defining tagged pointers in ergonomic way, even supporting different pointer types (`&`, `Box`, `Arc`, etc) as different `enum` variants. For example, the following code diff --git a/enum-ptr/src/lib.rs b/enum-ptr/src/lib.rs index 7b889ad..6666b27 100644 --- a/enum-ptr/src/lib.rs +++ b/enum-ptr/src/lib.rs @@ -147,9 +147,11 @@ //! //! ## Flavor 4: `map_ref` & `map_mut` *(legacy)* //! -//! [`map_ref`](Compact::map_ref) and [`map_mut`](Compact::map_mut) will create -//! temporary objects that drop as soon as your closure ends. They are -//! important for internal implementations, but less useful for lib users. +//! [`map_ref`](Compact::map_ref) and [`map_mut`](Compact::map_mut) will copy +//! (= [`core::mem::transmute_copy`]) temporary objects out of its compact ones, +//! that [`core::mem::forget`]-ed as soon as your closure ends, so that no +//! destructor is needed to be run. They are important for internal +//! implementations, but less useful for lib users. //! //!
//! Click to show examples diff --git a/enum-ptr/src/traits/aligned.rs b/enum-ptr/src/traits/aligned.rs index 5f954b1..8b38406 100644 --- a/enum-ptr/src/traits/aligned.rs +++ b/enum-ptr/src/traits/aligned.rs @@ -70,12 +70,32 @@ mod alloc_impl { const ALIGNMENT: usize = align_of::(); } - /// It makes assumption on the layout of `Rc`. Use it with caution. + /// Implementing [`Aligned`] for [`Rc`] relies on some undocumented + /// assumptions on its internal representation. However, it's very unlikely + /// for these assumptions to be violated in practice. + /// [`RcBox` is marked as `repr(C)` and reference counters are typed as `usize`][1]. + /// Thus, its alignment is defined as [the highest of its members][2] (i.e. among + /// max of `usize` and `T`). Lastly, it's unconceivable for the type to be + /// lifted with `repr(C)` as commented or to start to use shorter + /// integers as counters. + /// + /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/rc.rs.html#286-291 + /// [2]: https://doc.rust-lang.org/reference/type-layout.html#reprc-structs unsafe impl Aligned for Rc { const ALIGNMENT: usize = max(align_of::(), align_of::()); } - /// It makes assumption on the layout of `Arc`. Use it with caution. + /// Implementing [`Aligned`] for [`Arc`] relies on some undocumented + /// assumptions on its internal representation. However, it's very unlikely + /// for these assumptions to be violated in practice. + /// [`ArcInner` is marked as `repr(C)` and reference counters are typed as `usize`][1]. + /// Thus, its alignment is defined as [the highest of its members][2] (i.e. among + /// max of `usize` and `T`). Lastly, it's unconceivable for the type to be + /// lifted with `repr(C)` as commented or to start to use shorter + /// integers as counters. + /// + /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/sync.rs.html#349-359 + /// [2]: https://doc.rust-lang.org/reference/type-layout.html#reprc-structs unsafe impl Aligned for Arc { const ALIGNMENT: usize = max(align_of::(), align_of::()); } @@ -84,12 +104,26 @@ mod alloc_impl { const ALIGNMENT: usize = align_of::(); } - /// It makes assumption on the layout of `Rc`. Use it with caution. + /// On top of the safety reasoning of `impl Align for Rc`, implementing [`Aligned`] + /// for `Option>` is safe as well. `Rc` holds [a pointer to its `RcBox` as + /// `NonNull>`][1] + /// And the `Option`-ed type (i.e. `Option>>`) is explicitly guaranteed + /// to be [same as the original type in terms of size and alignment][2]. + /// + /// [1]: https://doc.rust-lang.org/1.81.0/src/alloc/rc.rs.html#315-322 + /// [2]: https://doc.rust-lang.org/nightly/std/option/index.html#representation unsafe impl Aligned for Option> { const ALIGNMENT: usize = max(align_of::(), align_of::()); } - /// It makes assumption on the layout of `Arc`. Use it with caution. + /// On top of the safety reasoning of `impl Align for Arc`, implementing [`Aligned`] + /// for `Option>` is safe as well. `Arc` holds [a pointer to its `ArcInner` as + /// `NonNull>`][1] + /// And the `Option`-ed type (i.e. `Option>>`) is explicitly guaranteed + /// to be [same as the original type in terms of size and alignment][2]. + /// + /// [1]: https://doc.rust-lang.org/nightly/src/alloc/sync.rs.html#241-248 + /// [2]: https://doc.rust-lang.org/nightly/std/option/index.html#representation unsafe impl Aligned for Option> { const ALIGNMENT: usize = max(align_of::(), align_of::()); } From 7fcd606e58156bf7d75dac389783cf1342325c93 Mon Sep 17 00:00:00 2001 From: Ryo Onodera Date: Mon, 7 Oct 2024 15:50:34 +0900 Subject: [PATCH 2/2] Add keywords for better discoverability --- Cargo.toml | 1 + enum-ptr-derive/Cargo.toml | 1 + enum-ptr/Cargo.toml | 1 + 3 files changed, 3 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index c640f91..dac211d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,6 +6,7 @@ resolver = "2" version = "0.2.0-beta.0" authors = ["QuarticCat "] description = "Ergonomic tagged pointer" +keywords = ["enum", "pointer", "tag", "tagged", "tagging"] readme = "README.md" repository = "https://github.com/QuarticCat/enum-ptr" documentation = "https://docs.rs/enum-ptr/" diff --git a/enum-ptr-derive/Cargo.toml b/enum-ptr-derive/Cargo.toml index af8eb79..0b61ddd 100644 --- a/enum-ptr-derive/Cargo.toml +++ b/enum-ptr-derive/Cargo.toml @@ -4,6 +4,7 @@ name = "enum-ptr-derive" version.workspace = true authors.workspace = true description.workspace = true +keywords.workspace = true readme.workspace = true repository.workspace = true documentation.workspace = true diff --git a/enum-ptr/Cargo.toml b/enum-ptr/Cargo.toml index 9ecac67..0f35767 100644 --- a/enum-ptr/Cargo.toml +++ b/enum-ptr/Cargo.toml @@ -4,6 +4,7 @@ name = "enum-ptr" version.workspace = true authors.workspace = true description.workspace = true +keywords.workspace = true readme.workspace = true repository.workspace = true documentation.workspace = true