Optimize label comparisons and remove restrictions on types that can be labels

[joseph-gio]

Objective

• Addresses concerns raised by cart in [Merged by Bors] - Add attribute to ignore fields of derived labels #5366.
• Make label comparisons O(1).
• More freedom for debug formatting.
• Be less prescriptive -- why should everything have to be only a string?

Solution

• Require implementers of Label to return a u64 value that distinguishes between labels of the same type.
• For formatting, store an &mut Formatter fn pointer.
  • Smaller stack size than a string slice.
  • More freedom than a string -- debug formatting can depend on runtime values or be composed generically.
• Store the TypeId and formatter behind the same pointer, shrinking the stack size of labels to 16 bytes (down from 24).
• The concept of labels not being allowed to hold data now applies only for the derive macro.
  • Anything that can fit in u64 can get stored on the stack for free.
  • Anything larger can be boxed -- simple types don't pay for what they don't use.
• Most of the complexity is contained to the derive macro: the base API remains fairly simple.

Examples

Basic labels.

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

//
// Derive expands to...

impl SystemLabel 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"),
            _ => unreachable!(),
        }
    }
}

Complex labels require boxing and interning.

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

//
// Derive expands to...

use bevy_ecs::label::{Labels, LabelGuard};

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

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

// Implementing this trait allows one to call `SystemLabelId::downcast` with this type.
impl<T: ...> LabelDowncast<SystemLabelId> for MyLabel<T> {
    // `LabelGuard` is just a type alias for a complex RwLock guard type.
    // We can choose any guard type depending on the implementation details,
    // but whatever type you choose, it will ultimately get hidden behind an opaque type.
    type Output = LabelGuard<'static, Self>;
    fn downcast_from(idx: u64) -> Option<LabelGuard<Self>> {
        // Return a reference to an interned value.
        MAP.get::<Self>(idx)
    }
}

Notes

• Label traits are no longer object safe, but this is probably a good thing since it makes it easier to catch obsolete instances of Box<dyn Label>. LabelId should always be used instead.
• 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.

Benchmarks

• Change since before this PR

# of Systems	No deps	% Change	W/ deps	% Change
100	224.77 us	-1.1679%	1.8170 ms	-4.6930%
500	761.30 us	+1.7829%	56.746 ms	-12.064%
1000	1.3880 ms	+2.2302%	288.34 ms	-10.231%

• Change since before this PR, with interning

# of Systems	No deps	% Change	W/ deps	% Change
100	201.52 us	-0.7881%	1.8720 ms	+2.5666%
500	766.45 us	-2.9538%	56.889 ms	-5.9933%
1000	1.3839 ms	-0.6838%	302.09 ms	+0.2272%

If we unnecessarily intern most of the labels in the benchmark, we see that it's still significantly faster than before #4957, which is the PR that originally removed boxed labels.

---

Changelog

• Removed as_str() and type_id() from label traits.

• Added data() and fmt() to label traits.
• Added support for complex label types by heap-allocating them.
• Fixed formatting of generics in Label derive macros.

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, the implementation has been changed entirely. Now, comparisons are done using the method .data(), which returns a u64 used to distinguish labels of the same type. Formatting is done through the associated fn fmt(), which writes to an &mut Formatter and is allowed to depend on runtime values.

[joseph-gio]

This PR is now at a point where I'm happy with it. I'll get CI passing once we yeet stringly-typed labels.

[joseph-gio]

On second thought, I realized that I can implement string-labels in this design. This PR is no longer blocked, not sure what that last CI failure is about though.

[DJMcNab]

Nowhere near a full review

[joseph-gio]

I've iterated a lot on this PR. In that time, the design and precise motivations have changed considerably and the history has gotten quite messy. I'm going to close this out and open a new PR.