Remove restrictions on Label types

[joseph-gio]

Redo of #5377

Background

Originally, label traits were essentially like Any, but with extra capabilities.

• This was unnecessarily slow, as it required boxing every label even though the vast majority are simply unit structs or C-style enums.
• Ignited months-long unresolved debates as to whether Box<dyn *Label> should implement the trait.
• Required a long list of derives for every implementer.
• O(?) comparisons due to dynamic dispatch.

In #4957, labels were simplified: they are represented as just a TypeId and a string literal.

• This sped up label comparisons and dependency resolution considerably, as allocations and dynamic dispatch are no longer necessary.
• Makes the use of labels more ergonomic, as their type-erased form is Copy. Additionally, none of the extra derives are required.
• It introduced major restrictions on what types can be labels: labels can only have names, not data.
• In most cases, this change was completely invisible to users.

Objective

• Remove the restrictions: allow labels to store any data that they want.
• Make complex labels faster than before [Merged by Bors] - Simplify design for *Labels #4957.
• Don't pessimize simple label types -- they should be just as fast as before this PR.
• Make comparisons O(1).
• Optimize the stack size of type-erased labels.
• Keep the user-facing API as simple as possible.

Solution

• Allow arbitrary debug formatting by writing to an &mut Formatter.
• For comparisons, use a u64.
  • Types that are 8 bytes or smaller can be encoded and stored inline.
  • For larger types, intern them and store their index. This also avoids duplicate allocations for identical labels.
  • Both of these cases are supported in the derive macro.
• Keep the stack size low by storing type-related data behind a pointer to an associated const.

Examples

Basic labels get converted to an integer and stored on the stack.

#[derive(SystemLabel)]
enum MyLabel {
    One,
    Two,
}

//
// Derive expands to...

impl IntoSystemLabel for MyLabel {
    fn data(&self) -> u64 {
        match self {
            Self::One => 0,
            Self::Two => 1,
        }
    }
    fn fmt(data: u64, f: &mut fmt::Formatter) -> fmt::Result {
        match data {
            0 => write!(f, "MyLabel::One"),
            1 => write!(f, "MyLabel::Two"),
            _ => Err(fmt::Error),
        }
    }
}

Complex labels get interned, with their index stored on the stack.

#[derive(Debug, Clone, PartialEq, Eq, Hash, SystemLabel)]
#[system_label(intern)]
pub struct MyLabel<T>(Vec<T>);

//
// Derive expands to...

use bevy_utils::{AnyInterner, InternGuard};

// Global label interner for `MyLabel<T>`, for any `T`.
static MAP: AnyInterner = AnyInterner::new();

impl<T: Debug + Clone + Hash + Eq + Send + Sync + 'static> IntoSystemLabel for MyLabel<T> {
    fn data(&self) -> u64 {
        MAP.intern(self)
    }
    fn fmt(idx: u64, f: &mut Formatter) -> fmt::Result {
        let val = MAP.get::<Self>(idx).ok_or(fmt::Error)?;
        write!(f, "{val:?}")
    }
}

Benchmarks

Relative to before this PR.

• Using stack-allocated labels.

# of Systems	No deps	% Change	W/ deps	% Change
100	235.51 us	-0.9142%	1.8465 ms	-9.2033%
500	782.39 us	+0.1074%	61.109 ms	-15.269%
1000	1.4279 ms	+1.0771%	310.41 ms	-13.131%

• Heap-allocating everything.

# of Systems	No deps	% Change	W/ deps	% Change
100	233.20 us	+1.0003%	2.0064 ms	+1.5735%
500	789.80 us	-0.9972%	64.846 ms	-6.1881%
1000	1.4699 ms	-2.0041%	318.41 ms	-5.2037%

Notes

• This PR adds parking_lot and indexmap as dependencies for bevy_utils.
  • indexmap only has one dependency (hashbrown), which is already a dependency of bevy_utils.

Future Work

• We can clean up unused memory by emptying out the global interners after dependency resolution is complete. This would break debug formatting, but comparisons would still work perfectly.
• Downcasting can easily be implemented, but the API decisions are left for a future PR.

---

Changelog

• Made the internal representation of labels more flexible.
• Added support for complex label types by interning them.

Migration Guide

The Label family of traits (SystemLabel, StageLabel, etc) is no longer object safe.

• Any use of Box<dyn *Label> should be replaced with *LabelId - this family of types serves the same purpose but is Copy and does not usually require allocations.
• Any use of &dyn *Label should be replaced with impl *Label if possible, or *LabelId if you cannot use generics.

For manual implementers of this family of traits, you should now implement the corresponding Into*Label trait.

enum GameLabel {
    Input,
    Physics,
}

// Before:

impl SystemLabel for GameLabel {
    fn as_str(&self) -> &'static str {
        match self {
            Self::Input => "GameLabel::Input",
            Self::Physics => "GameLabel::Physics",
        }
    }
}

// After:

impl IntoSystemLabel for GameLabel {
    fn data(&self) -> u64 {
        match self {
            Self::Input => 0,
            Self::Physics => 1,
        }
    }
    fn fmt(data: u64, f: &mut Formatter) -> fmt::Result {
        match data {
            0 => write!(f, "GameLabel::Input"),
            1 => write!(f, "GameLabel::Physics"),
            _ => Err(fmt::Error),
        }
    }
}

[alice-i-cecile]

This is an exceptional writeup, and I agree with the motivations here. A bit annoying to increase the complexity of this niche area further, but I think the expressiveness and performance will be worth it.

[alice-i-cecile]

Really nice work. Exceptional docs, error messages and general technical proficiency here.

There's a few nits and open questions for me, but I'm generally on board here.

[alice-i-cecile]

@JoJoJet is this still relevant?

[joseph-gio]

Nah, I have no intention to update this.