Support non-Vec data structures in relations

[alice-i-cecile]

Objective

The existing RelationshipSourceCollection uses Vec as the only possible backing for our relationships. While a reasonable choice, benchmarking use cases might reveal that a different data type is better or faster.

For example:

• Not all relationships require a stable ordering between the relationship sources (i.e. children). In cases where we a) have many such relations and b) don't care about the ordering between them, a hash set is likely a better datastructure than a Vec.
• The number of children-like entities may be small on average, and a smallvec may be faster

Solution

• Implement RelationshipSourceCollection for EntityHashSet, our custom entity-optimized HashSet.
  -Implement DoubleEndedIterator for EntityHashSet to make things compile.
  • This implementation was cursed and very surprising.
  • Instead, by moving the iterator type on RelationshipSourceCollection from an erased RPTIT to an explicit associated type we can add a trait bound on the offending methods!
• Implement RelationshipSourceCollection for SmallVec

Testing

I've added a pair of new tests to make sure this pattern compiles successfully in practice!

Migration Guide

EntityHashSet and EntityHashMap are no longer re-exported in bevy_ecs::entity directly. If you were not using bevy_ecs / bevy's prelude, you can access them through their now-public modules, hash_set and hash_map instead.

Notes to reviewers

The EntityHashSet::Iter type needs to be public for this impl to be allowed. I initially renamed it to something that wasn't ambiguous and re-exported it, but as @Victoronz pointed out, that was somewhat unidiomatic.

In 1a85648, I instead made the entity_hash_set public (and its entity_hash_set) sister public, and removed the re-export. I prefer this design (give me module docs please), but it leads to a lot of churn in this PR.

Let me know which you'd prefer, and if you'd like me to split that change out into its own micro PR.

[bushrat011899]

Nice!

[bushrat011899]

This is definitely the right path forward. RPIT is great 90% of the time, but this is that 10% case.

[alice-i-cecile]

It's a mouthful, but I really think that the added flexibility / correctness is worth it here.

[Victoronz]

Are these not available via the Deref to the inner hashbrown set?

[alice-i-cecile]

Just relying on the Deref impl was failing for these, as the compiler was getting confused about the circular trait methods due to the same name / signature.

[Victoronz]

ah, that is because of method resolution!
when len is an inherent method on self, then self.len() in a len() trait method impl works, but if the inherent len() is down a step in the deref chain, the trait method on self resolves first, resulting in a cycle.
The solution should be any of self.0.len()/(*self).len()/self.deref().len() in the trait method impl.

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Could you add some context on what users should update when this change get released in a new version of Bevy?
It will be used to help writing the migration guide for the version. Putting it after a ## Migration Guide will help it get automatically picked up by our tooling.