library: core: document layout guarantee of TypeId

[dakr]

Document the layout guarantee of TypeId not to exceed 16 bytes.

This is useful for FFI use-cases where a TypeId may be stored within a foreign data structure or buffer.

An example for such a use-case can be found in [1].

Link: https://git.kernel.org/pub/scm/linux/kernel/git/driver-core/driver-core.git/commit/?id=6f61a2637abe4f89877da3280775565baedb60e0 [1]
Suggested-by: Alice Ryhl aliceryhl@google.com

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[dakr]

Cc: @Darksonn

[scottmcm]

Do you have a reference to a place where there was an agreement to commit to this? Or is this a new libs-api/libs/compiler request?

[Darksonn]

Do you have a reference to a place where there was an agreement to commit to this? Or is this a new libs-api/libs/compiler request?

This PR is a request for the stdlib to make this commitment. There is some prior discussion at #rust-for-linux > TypeId layout.

[jieyouxu]

This was discussed during this Thursday's compiler triage meeting #t-compiler/meetings > [weekly] 2025-10-30 @ 💬. The consensus of those present at the meeting was:

• We were not ready to commit to any stability guarantees surrounding TypeId's size or layout before the collision-resistance concerns (Collisions in type_id #10389, type_id is not sufficiently collision-resistant #129014) were resolved.
• Committing to a size upper bound now would close the door for making TypeId larger in the future.
  • Even if we are

  at least soft-bound to not go above 16bytes just from the fact that making the type too large would be bad for perf for people who rely heavily on TypeId

There was also an alternative approach for this use case that was discussed during the meeting. For FFI purposes, can TypeId be boxed and treated as an opaque pointer instead? This seems like something that RfL can wrap and make additional size guarantees on top of.

The TL;DR is that we'd prefer not to guarantee this until we decide on what to do about typeid collisions.

@rustbot label: -I-compiler-nominated

[Noratrieb]

I disagree with that, and I have opened a Zulip thread to further discuss it, so don't take the above message as a final compiler decision yet, it may or may not change:
https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/TypeId.20minimum.20size.20guarantees/with/553234173

[ChrisDenton]

I would emphasize that restricting TypeId to 16 bytes only restricts the inline size, not the total size in the binary. I don't think we'd be closing the door on 256, 512 or 1024 bit hashes or even full v0 name mangling if we wanted to go down that route.

[programmerjake]

as mentioned on Zulip, I think we can guarantee TypeId's size is no bigger than:

#[repr(C)]
union TypeIdBytes {
    a: u128,
    b: [*const (); 2], // not usize since that may not match pointer size on CHERI
}

To be clear, I'm not proposing that TypeId becomes that union, just that it fits in that union when written with ptr::write_unaligned.

That is 16 bytes except for platforms where pointers are >8 bytes (e.g. CHERI or rv128i).

This properly handles our current implementation of having just a 128-bit hash, as well as larger values by letting us have:

#[repr(C)]
pub struct TypeId {
    small_hash: u64,
    full_data: &'static FullData, // e.g. a ThinCStr or a >=256-bit hash
}

impl PartialEq for TypeId {
    fn eq(&self, other: &Self) -> bool {
        if self.small_hash != other.small_hash {
            false // fast not-equal
        } else if ptr::eq(self.full_data, other.full_data) {
            true // fast equal, can be made the usual case by e.g. linker deduplication
        } else {
            self.full_data == other.full_data // rare slow path
        }
    }
}

[bors]

☔ The latest upstream changes (presumably #148425) made this pull request unmergeable. Please resolve the merge conflicts.

[dakr]

Given that #148394 has just been sent and merged, are we further discussing this?

[ChrisDenton]

#148394 was explicitly not a decision either way. It just documents the status quo.

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[scottmcm]

Given that #148394 has just been sent and merged

For clarity: I merged that as "currently factual", but explicitly expecting that it might change by this PR (or others).

If we end up making a confident decision quickly, great. If it ends up taking while, while at least we have the explicit note in the mean time :)

[the8472]

We discussed this during today's libs-api meeting. Since TypeId is not really implemented by the library itself and its internals are driven by compiler concerns we're largely ok with deferring to T-compiler on which guarantees they're willing to give / how much they want to constrain their future implementations.

One concern we have is the binary size bloat that some of the possible future implementations would cause. Putting the typename behind the pointer could lead to significant binary size increase for crates that make heavy use of type IDs and has long type names. We want TypeId to remain a cheap type so that crates that use it a lot or embedded systems don't run into scaling issues.

[programmerjake]

should this be nominated again for t-compiler to decide if they want the solution I proposed?