Remove unions

Author: SanderMertens

distr/flecs.c

@@ -441,11 +441,10 @@ extern "C" {
 #define EcsIdIsSparse                  (1u << 23)
 #define EcsIdDontFragment              (1u << 24)
 #define EcsIdMatchDontFragment         (1u << 25) /* For (*, T) wildcards */
-#define EcsIdIsUnion                   (1u << 26)
 #define EcsIdOrderedChildren           (1u << 28)
 #define EcsIdEventMask\
     (EcsIdHasOnAdd|EcsIdHasOnRemove|EcsIdHasOnSet|\
-        EcsIdHasOnTableCreate|EcsIdHasOnTableDelete|EcsIdIsSparse|EcsIdIsUnion|\
+        EcsIdHasOnTableCreate|EcsIdHasOnTableDelete|EcsIdIsSparse|\
         EcsIdOrderedChildren)
 
 #define EcsIdMarkedForDelete           (1u << 30)
@@ -549,9 +548,8 @@ extern "C" {
 #define EcsTermIsToggle               (1u << 10)
 #define EcsTermKeepAlive              (1u << 11)
 #define EcsTermIsSparse               (1u << 12)
-#define EcsTermIsUnion                (1u << 13)
-#define EcsTermIsOr                   (1u << 14)
-#define EcsTermDontFragment           (1u << 15)
+#define EcsTermIsOr                   (1u << 13)
+#define EcsTermDontFragment           (1u << 14)
 
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -599,7 +597,6 @@ extern "C" {
 #define EcsTableHasSparse              (1u << 23u)
 #define EcsTableHasDontFragment        (1u << 24u)
 #define EcsTableOverrideDontFragment   (1u << 25u)
-#define EcsTableHasUnion               (1u << 26u)
 
 #define EcsTableHasTraversable         (1u << 27u)
 #define EcsTableHasOrderedChildren     (1u << 28u)
@@ -611,9 +608,9 @@ extern "C" {
 #define EcsTableIsComplex        (EcsTableHasLifecycle | EcsTableHasToggle | EcsTableHasSparse)
 #define EcsTableHasAddActions    (EcsTableHasIsA | EcsTableHasCtors | EcsTableHasOnAdd | EcsTableHasOnSet)
 #define EcsTableHasRemoveActions (EcsTableHasIsA | EcsTableHasDtors | EcsTableHasOnRemove)
-#define EcsTableEdgeFlags        (EcsTableHasOnAdd | EcsTableHasOnRemove | EcsTableHasSparse | EcsTableHasUnion)
-#define EcsTableAddEdgeFlags     (EcsTableHasOnAdd | EcsTableHasSparse | EcsTableHasUnion)
-#define EcsTableRemoveEdgeFlags  (EcsTableHasOnRemove | EcsTableHasSparse | EcsTableHasUnion | EcsTableHasOrderedChildren)
+#define EcsTableEdgeFlags        (EcsTableHasOnAdd | EcsTableHasOnRemove | EcsTableHasSparse)
+#define EcsTableAddEdgeFlags     (EcsTableHasOnAdd | EcsTableHasSparse)
+#define EcsTableRemoveEdgeFlags  (EcsTableHasOnRemove | EcsTableHasSparse | EcsTableHasOrderedChildren)
 
 ////////////////////////////////////////////////////////////////////////////////
 //// Aperiodic action flags (used by ecs_run_aperiodic)
@@ -1990,87 +1987,6 @@ void ecs_map_copy(
 
 #endif
 
-/**
- * @file switch_list.h
- * @brief Interleaved linked list for storing mutually exclusive values.
- */
-
-#ifndef FLECS_SWITCH_LIST_H
-#define FLECS_SWITCH_LIST_H
-
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef struct ecs_switch_node_t {
-    uint32_t next;      /* Next node in list */
-    uint32_t prev;      /* Prev node in list */
-} ecs_switch_node_t;
-
-typedef struct ecs_switch_page_t {
-    ecs_vec_t nodes;    /* vec<ecs_switch_node_t> */
-    ecs_vec_t values;   /* vec<uint64_t> */
-} ecs_switch_page_t;
-
-typedef struct ecs_switch_t {
-    ecs_map_t hdrs;     /* map<uint64_t, uint32_t> */
-    ecs_vec_t pages;    /* vec<ecs_switch_page_t> */
-} ecs_switch_t;
-
-/** Init new switch. */
-FLECS_DBG_API
-void flecs_switch_init(
-    ecs_switch_t* sw,
-    ecs_allocator_t *allocator);
-
-/** Fini switch. */
-FLECS_DBG_API
-void flecs_switch_fini(
-    ecs_switch_t *sw);
-
-/** Set value of element. */
-FLECS_DBG_API
-bool flecs_switch_set(
-    ecs_switch_t *sw,
-    uint32_t element,
-    uint64_t value);
-
-/** Reset value of element. */
-FLECS_DBG_API
-bool flecs_switch_reset(
-    ecs_switch_t *sw,
-    uint32_t element);
-
-/** Get value for element. */
-FLECS_DBG_API
-uint64_t flecs_switch_get(
-    const ecs_switch_t *sw,
-    uint32_t element);
-
-/** Get first element for value. */
-FLECS_DBG_API
-uint32_t flecs_switch_first(
-    const ecs_switch_t *sw,
-    uint64_t value);
-
-/** Get next element. */
-FLECS_DBG_API
-uint32_t flecs_switch_next(
-    const ecs_switch_t *sw,
-    uint32_t previous);
-
-/** Get target iterator. */
-FLECS_DBG_API
-ecs_map_iter_t flecs_switch_targets(
-    const ecs_switch_t *sw);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif
-
 /**
  * @file allocator.h
  * @brief Allocator that returns memory objects of any size. 
@@ -5700,9 +5616,6 @@ FLECS_API extern const ecs_entity_t EcsSparse;
 /** Mark component as non-fragmenting */
 FLECS_API extern const ecs_entity_t EcsDontFragment;
 
-/** Mark relationship as union */
-FLECS_API extern const ecs_entity_t EcsUnion;
-
 /** Marker used to indicate `$var == ...` matching in queries. */
 FLECS_API extern const ecs_entity_t EcsPredEq;
 
@@ -17968,7 +17881,6 @@ static const flecs::entity_t Symbol = EcsSymbol;
 /* Storage */
 static const flecs::entity_t Sparse = EcsSparse;
 static const flecs::entity_t DontFragment = EcsDontFragment;
-static const flecs::entity_t Union = EcsUnion;
 
 /* Builtin predicates for comparing entity ids in queries. */
 static const flecs::entity_t PredEq = EcsPredEq;
@@ -31095,24 +31007,6 @@ namespace _ {
         void populate(const Builder& b) {
             size_t i = 0;
             for (auto id : ids) {
-               if (!(id & ECS_ID_FLAGS_MASK)) {
-                    const flecs::type_info_t *ti = ecs_get_type_info(world_, id);
-                    if (ti) {
-                        // Union relationships always return a value of type
-                        // flecs::entity_t which holds the target id of the 
-                        // union relationship.
-                        // If a union component with a non-zero size (like an 
-                        // enum) is added to the query signature, the each/iter
-                        // functions would accept a parameter of the component
-                        // type instead of flecs::entity_t, which would cause
-                        // an assert.
-                        ecs_assert(
-                            !ti->size || !ecs_has_id(world_, id, flecs::Union),
-                            ECS_INVALID_PARAMETER,
-                            "use with() method to add union relationship");
-                    }
-                }
-
                 b->with(id).inout(inout[i]).oper(oper[i]);
                 i ++;
             }

distr/flecs.h

@@ -1685,74 +1685,6 @@ assert!(e.is_enabled::<Position>());
 </ul>
 </div>
 
-## Union trait
-The `Union` is similar to `Exclusive` in that it enforces that an entity can have only a single instance of a relationship. The difference between `Exclusive` and `Union` is that `Union` combines different relationship targets in a single table. This reduces table fragmentation, and as a result speeds up add/remove operations. This increase in add/remove speed does come at a cost: iterating a query with union terms is more expensive than iterating a regular relationship.
-
-The API for using the `Union` trait is similar to regular relationships, as this example shows:
-
-<div class="flecs-snippet-tabs">
-<ul>
-<li><b class="tab-title">C</b>
-
-```c
-ecs_entity_t Movement = ecs_new(world);
-ecs_add_id(world, Movement, EcsUnion);
-
-ecs_entity_t Walking = ecs_new(world);
-ecs_entity_t Running = ecs_new(world);
-
-ecs_entity_t e = ecs_new(world);
-ecs_add_pair(world, e, Movement, Running);
-ecs_add_pair(world, e, Movement, Walking); // replaces (Movement, Running)
-```
-
-</li>
-<li><b class="tab-title">C++</b>
-
-```cpp
-flecs::entity Movement = world.entity().add(flecs::Union);
-flecs::entity Walking = world.entity();
-flecs::entity Running = world.entity();
-
-flecs::entity e = world.entity().add(Movement, Running);
-e.add(Movement, Walking); // replaces (Movement, Running)
-```
-
-</li>
-<li><b class="tab-title">C#</b>
-
-```cs
-Entity movement = world.Entity().Add(Ecs.Union);
-Entity walking = world.Entity();
-Entity running = world.Entity();
-
-Entity e = world.Entity().Add(movement, running);
-e.Add(movement, walking); // replaces (Movement, Running)
-```
-
-</li>
-<li><b class="tab-title">Rust</b>
-
-```rust
-let movement = world.entity().add_trait::<flecs::Union>();
-let walking = world.entity();
-let running = world.entity();
-
-let e = world.entity().add_id((movement, running));
-e.add_id((movement, walking)); // replaces (Movement, Running)
-```
-
-</li>
-</ul>
-</div>
-
-When compared to regular relationships, union relationships have some differences and limitations:
-- Relationship cleanup does not work yet for union relationships
-- Removing a union relationship removes any target, even if the specified target is different
-- Union relationships cannot have data
-
-Support for the `Union` trait will be deprececated soon and replaced by exclusive `DontFragment` relationships.
-
 ## Sparse trait
 The `Sparse` trait configures a component to use sparse storage. Sparse components are stored outside of tables, which means they do not have to be moved. Sparse components are also guaranteed to have stable pointers, which means that a component pointer is not invalidated when an entity moves to a new table. ECS operations and queries work as expected with sparse components.
 

docs/ComponentTraits.md

@@ -490,9 +490,16 @@ world.entity()
 </div>
 
 ## Union relationships
-In v3, Union relationships where encoded on the entity type with a `(Union, Relationship)` pair. In v4, union relationships are encoded with a `(Relationship, Union)` pair.
+Union relationships have been replaced with `DontFragment, Exclusive` relationships. See the ComponentTraits manual for more information on `DontFragment` relationships.
 
-The API for unions has not changed meaningfully. However, the union storage has changed, which might impact performance (positively or negatively).
+```cpp
+// Old
+world.component<Position>().add(flecs::Union);
+```
+```cpp
+// New
+world.component<Position>().add(flecs::DontFragment).add(flecs::Exclusive);
+```
 
 ## Snapshots
 The snapshot feature has been removed from v4.

docs/MigrationGuide.md

@@ -971,7 +971,7 @@ When a prefab hierarchy is instantiated often code will want to refer to a speci
 
 While it is possible to lookup a child by name and store it on a component, this adds boilerplate and reduces efficiency. Prefab slots make this easier.
 
-A prefab child can be created as a slot. Slots are created as relationships on the instance, with as target of the relationship the instantiated child. The slot is added as a union relationship which doesn't fragment archetypes.
+A prefab child can be created as a slot. Slots are created as relationships on the instance, with as target of the relationship the instantiated child. The slot is added as a `DontFragment` relationship which doesn't fragment archetypes.
 
 The following example shows how to create and use a prefab slot:
 

docs/PrefabsManual.md

@@ -2918,7 +2918,6 @@ This list is an overview of current relationship traversal limitations:
 
 - The `Cascade` and `Desc` flags require caching.
 - Traversal flags can only be specified for the term source.
-- Union relationship queries that are not wildcards are not supported for traversal.
 
 The following sections show how to use traversal in the different language bindings.
 
@@ -3355,7 +3354,7 @@ q.iterable().set_var_expr("$Location", earth).each(|it| {
 </div>
 
 ### Member Value Queries
-Queries can match against the values of component members if they are of the `ecs_entity_t` type, and the component type is described with the reflection framework. Member value queries make it possible to query on values that can change rapidly without requiring structural changes in the ECS. The tradeoff is that other than with the regular, union and toggle storage options there are no acceleration structures to speed up query evaluation, which means that a query has to evaluate each instance of the component.
+Queries can match against the values of component members if they are of the `ecs_entity_t` type, and the component type is described with the reflection framework. Member value queries make it possible to query on values that can change rapidly without requiring structural changes in the ECS. The tradeoff is that other than with the regular, `DontFragment` and `CanToggle` storage options there are no acceleration structures to speed up query evaluation, which means that a query has to evaluate each instance of the component.
 
 The following sections show how to use queries in the different language bindings.
 

docs/Queries.md

@@ -1876,7 +1876,7 @@ Fragmentation is a property of archetype-based ECS implementations where entitie
 
 Applications that make extensive use of relationships might observe high levels of fragmentation, as relationships can introduce many different combinations of components. While the Flecs storage is optimized for supporting large amounts (hundreds of thousands) of tables, fragmentation is a factor to consider when using relationships.
 
-Fragmentation can be reduced by using [union relationships](#union-property). There are additional storage improvements on the roadmap that will decrease the overhead of fragmentation introduced by relationships.
+Fragmentation can be reduced by using DontFragment relationships. There are additional storage improvements on the roadmap that will decrease the overhead of fragmentation introduced by relationships.
 
 ### Table Creation
 When an id added to an entity is deleted, all references to that id are deleted from the storage (see [cleanup properties](#cleanup-properties)). For example, when the component `Position` is deleted it is removed from all entities, and all tables with the `Position` component are deleted. While not unique to relationships, it is more common for relationships to trigger cleanup actions, as relationship pairs contain regular entities.