From 54459dfbc149b29cd493d7ab9b9eb8ba19f514be Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Tue, 16 Jun 2026 10:02:54 -0400 Subject: [PATCH 1/9] Distinguish `repr(C)` ZSTs from others in ABI compatibility rules --- library/core/src/primitive_docs.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index d80c55538055b..acbf9a126b85b 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1858,7 +1858,14 @@ mod prim_ref {} /// call will be valid ABI-wise. The callee receives the result of transmuting the function pointer /// from `fn()` to `fn(i32)`; that transmutation is itself a well-defined operation, it's just /// almost certainly UB to later call that function pointer.) -/// - Any two types with size 0 and alignment 1 are ABI-compatible. +/// - Any two types fulfilling all the following conditions are ABI-compatible; +/// such types are said to have "trivial ABI": +/// - Size 0 +/// - Alignment 1 +/// - Not `repr(C)` +/// - Not a `repr(transparent)` wrapper around a type that fails to satisfy these conditions +/// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI +/// (as defined above). If there is no such field, the type has trivial ABI. /// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the /// unique field that doesn't have size 0 and alignment 1 (if there is such a field). /// - `i32` is ABI-compatible with `NonZero`, and similar for all other integer types. From 2f9ad4416c86ca9de6cba6cac47c6aca5dc6c439 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Fri, 19 Jun 2026 14:54:37 -0400 Subject: [PATCH 2/9] Make most arrays non-trivial --- library/core/src/primitive_docs.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index acbf9a126b85b..a8a60c8c580b3 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1864,6 +1864,7 @@ mod prim_ref {} /// - Alignment 1 /// - Not `repr(C)` /// - Not a `repr(transparent)` wrapper around a type that fails to satisfy these conditions +/// - Not an array whose element type fails to satisfy these conditions /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI /// (as defined above). If there is no such field, the type has trivial ABI. /// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the From f64a23af1eedfc2190190b72ea8cd1ab36c915cc Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Thu, 2 Jul 2026 10:29:18 -0400 Subject: [PATCH 3/9] Improve wording --- library/core/src/primitive_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index a8a60c8c580b3..6f354145ce4ec 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1863,8 +1863,8 @@ mod prim_ref {} /// - Size 0 /// - Alignment 1 /// - Not `repr(C)` -/// - Not a `repr(transparent)` wrapper around a type that fails to satisfy these conditions -/// - Not an array whose element type fails to satisfy these conditions +/// - If `repr(transparent)`, all field types must have trivial ABI +/// - If an array, the element type must have trivial ABI /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI /// (as defined above). If there is no such field, the type has trivial ABI. /// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the From 207c80134dcfa211b510b5b2e140145ac2c37c8e Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Thu, 2 Jul 2026 13:15:33 -0400 Subject: [PATCH 4/9] Future-proofing --- library/core/src/primitive_docs.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 6f354145ce4ec..15f085c449d1a 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1865,6 +1865,8 @@ mod prim_ref {} /// - Not `repr(C)` /// - If `repr(transparent)`, all field types must have trivial ABI /// - If an array, the element type must have trivial ABI +/// - Note: additional conditions may be added in future versions of Rust, +/// to exclude types newly introduced in those versions /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI /// (as defined above). If there is no such field, the type has trivial ABI. /// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the From 1178cd3605b1699ad9e3b69f794b595447b73fcb Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Thu, 2 Jul 2026 22:13:39 -0400 Subject: [PATCH 5/9] Improve wording Co-authored-by: Brian Smith Co-authored-by: Ralf Jung --- library/core/src/primitive_docs.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 15f085c449d1a..db2ae1833d1d8 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1860,17 +1860,17 @@ mod prim_ref {} /// almost certainly UB to later call that function pointer.) /// - Any two types fulfilling all the following conditions are ABI-compatible; /// such types are said to have "trivial ABI": -/// - Size 0 -/// - Alignment 1 -/// - Not `repr(C)` -/// - If `repr(transparent)`, all field types must have trivial ABI -/// - If an array, the element type must have trivial ABI -/// - Note: additional conditions may be added in future versions of Rust, -/// to exclude types newly introduced in those versions +/// - It has size 0. +/// - It has alignment 1. +/// - One of the following apply: +/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields). +/// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]). +/// - It is a `repr(transparent)` `struct`, `enum`, or `union`, and all fields have trivial ABI. +/// - It is an array, and its element type has trivial ABI. (Arrays of length 0 are not exempt from this requirement.) +/// - It is [the never type `!`][prim_never]. +/// - It is a function item type or closure type. /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI -/// (as defined above). If there is no such field, the type has trivial ABI. -/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the -/// unique field that doesn't have size 0 and alignment 1 (if there is such a field). +/// (as defined above), if such a field exists. /// - `i32` is ABI-compatible with `NonZero`, and similar for all other integer types. /// - If `T` is guaranteed to be subject to the [null pointer /// optimization](option/index.html#representation), and `E` is an enum satisfying the following From 45dfb46ed43de0f26653953ca7724e56b461bdbf Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Sat, 4 Jul 2026 10:39:08 -0400 Subject: [PATCH 6/9] Avoid negation Co-authored-by: Ralf Jung --- library/core/src/primitive_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index db2ae1833d1d8..cd3680ea0575c 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1866,7 +1866,7 @@ mod prim_ref {} /// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields). /// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]). /// - It is a `repr(transparent)` `struct`, `enum`, or `union`, and all fields have trivial ABI. -/// - It is an array, and its element type has trivial ABI. (Arrays of length 0 are not exempt from this requirement.) +/// - It is an array, and its element type has trivial ABI. (This requirement applies even to arrays of length 0.) /// - It is [the never type `!`][prim_never]. /// - It is a function item type or closure type. /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI From f832c93382cb489beee22566d3f84daeaed1ece3 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Sun, 19 Jul 2026 20:59:42 -0400 Subject: [PATCH 7/9] "flags" -> "modifiers" --- library/core/src/primitive_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index cd3680ea0575c..8fbddd4dc8025 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1863,7 +1863,7 @@ mod prim_ref {} /// - It has size 0. /// - It has alignment 1. /// - One of the following apply: -/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional flags such as `packed`) `struct`, `enum`, `union` (regardless of its fields). +/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional modifiers such as `packed`) `struct`, `enum`, `union` (regardless of its fields). /// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]). /// - It is a `repr(transparent)` `struct`, `enum`, or `union`, and all fields have trivial ABI. /// - It is an array, and its element type has trivial ABI. (This requirement applies even to arrays of length 0.) From fd75d005f494f472eb049d851c1d692f158d5d70 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Mon, 20 Jul 2026 08:04:13 -0400 Subject: [PATCH 8/9] Add clarifying note about all-trivial `repr(transparent)` Co-authored-by: Ralf Jung --- library/core/src/primitive_docs.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 8fbddd4dc8025..715faebedc443 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1870,7 +1870,7 @@ mod prim_ref {} /// - It is [the never type `!`][prim_never]. /// - It is a function item type or closure type. /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI -/// (as defined above), if such a field exists. +/// (as defined above), if such a field exists. (Note that if no such field exists, then the `repr(transparent)` type itself has trivial ABI, so the case above applies.) /// - `i32` is ABI-compatible with `NonZero`, and similar for all other integer types. /// - If `T` is guaranteed to be subject to the [null pointer /// optimization](option/index.html#representation), and `E` is an enum satisfying the following From 3653c35c428bb2ed9fdfebea26f7106f2684f6bc Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Thu, 13 Aug 2026 10:36:14 -0400 Subject: [PATCH 9/9] Mention unstable types + minor rephrase Co-authored-by: Ralf Jung --- library/core/src/primitive_docs.rs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 715faebedc443..e46b9298f4771 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1858,16 +1858,19 @@ mod prim_ref {} /// call will be valid ABI-wise. The callee receives the result of transmuting the function pointer /// from `fn()` to `fn(i32)`; that transmutation is itself a well-defined operation, it's just /// almost certainly UB to later call that function pointer.) -/// - Any two types fulfilling all the following conditions are ABI-compatible; -/// such types are said to have "trivial ABI": +/// - Any two types with "trivial ABI" are ABI-compatible. +/// A type has trivial ABI if is satisfies all of the following: /// - It has size 0. /// - It has alignment 1. /// - One of the following apply: -/// - It is a `repr(Rust)` (implicitly or explicitly, possibly with additional modifiers such as `packed`) `struct`, `enum`, `union` (regardless of its fields). +/// - It is a `repr(Rust)` (implicitly or explicitly) `struct`, `enum`, `union` (regardless of its fields, +/// and possibly with additional `repr` modifiers such as `packed`). /// - It is a [tuple][prim_tuple] (regardless of its fields, and including [`()`][prim_unit]). /// - It is a `repr(transparent)` `struct`, `enum`, or `union`, and all fields have trivial ABI. /// - It is an array, and its element type has trivial ABI. (This requirement applies even to arrays of length 0.) /// - It is [the never type `!`][prim_never]. +// - It is a pattern type or an unsafe binder type, and the inner type has trivial ABI. +// (These are still unstable so intentionally not included in the user-visible doc comment, as their rules may change.) /// - It is a function item type or closure type. /// - A `repr(transparent)` type is ABI-compatible with its unique field that does not have trivial ABI /// (as defined above), if such a field exists. (Note that if no such field exists, then the `repr(transparent)` type itself has trivial ABI, so the case above applies.)