Flecs
v4.1
Flecs
v4.1
Functions | |
| bool | ecs_readonly_begin (ecs_world_t *world, bool multi_threaded) |
| Begin readonly mode. | |
| void | ecs_readonly_end (ecs_world_t *world) |
| End readonly mode. | |
| void | ecs_merge (ecs_world_t *stage) |
| Merge a stage. | |
| bool | ecs_is_stage (const ecs_world_t *world) |
| Test whether a world object is a stage. | |
| void | ecs_set_stage_count (ecs_world_t *world, int32_t stages) |
| Configure the world to have N stages. | |
| int32_t | ecs_get_stage_count (const ecs_world_t *world) |
| Get the number of configured stages. | |
| ecs_world_t * | ecs_get_stage (const ecs_world_t *world, int32_t stage_id) |
| Get stage-specific world pointer. | |
| bool | ecs_stage_is_readonly (const ecs_world_t *world) |
| Test whether the current world is readonly. | |
| ecs_world_t * | ecs_stage_new (ecs_world_t *world) |
| Create an unmanaged stage. | |
| void | ecs_stage_free (ecs_world_t *stage) |
| Free an unmanaged stage. | |
| int32_t | ecs_stage_get_id (const ecs_world_t *world) |
| Get the stage ID. | |
| ecs_world_t * ecs_get_stage | ( | const ecs_world_t * | world, |
| int32_t | stage_id ) |
Get stage-specific world pointer.
Flecs threads can safely invoke the API as long as they have a private context to write to, also referred to as the stage. This function returns a pointer to a stage, disguised as a world pointer.
Note that this function does not create a new world. It simply wraps the existing world in a thread-specific context, which the API knows how to unwrap. The reason the stage is returned as an ecs_world_t is so that it can be passed transparently to the existing API functions, instead of having to create a dedicated API for threading.
| world | The world. |
| stage_id | The index of the stage to retrieve. |
| int32_t ecs_get_stage_count | ( | const ecs_world_t * | world | ) |
Get the number of configured stages.
Return the number of stages set by ecs_set_stage_count().
| world | The world. |
| bool ecs_is_stage | ( | const ecs_world_t * | world | ) |
Test whether a world object is a stage.
Operations on a stage are enqueued until the stage is merged.
| world | The world or stage. |
| void ecs_merge | ( | ecs_world_t * | stage | ) |
Merge a stage.
This will merge all commands enqueued for a stage.
| stage | The stage. |
| bool ecs_readonly_begin | ( | ecs_world_t * | world, |
| bool | multi_threaded ) |
Begin readonly mode.
This operation puts the world in readonly mode, which disallows mutations on the world. Readonly mode exists so that internal mechanisms can implement optimizations that assume certain aspects of the world do not change, while also providing a mechanism for applications to prevent accidental mutations in, for example, multithreaded applications.
Readonly mode is a stronger version of deferred mode. In deferred mode, ECS operations such as add, remove, set, delete, etc. are added to a command queue to be executed later. In readonly mode, operations that could break scheduler logic (such as creating systems, queries) are also disallowed.
Readonly mode itself has a single-threaded and a multithreaded mode. In single-threaded mode, certain mutations on the world are still allowed, for example:
These mutations are safe in single-threaded applications, but for multithreaded applications the world needs to be entirely immutable. For this purpose, multithreaded readonly mode exists, which disallows all mutations on the world. This means that in multithreaded applications, entity liveliness operations, implicit component registration, and on-the-fly query creation are not guaranteed to work.
While in readonly mode, applications can still enqueue ECS operations on a stage. Stages are managed automatically when using the pipeline addon and ecs_progress(), but they can also be configured manually as shown here:
When an attempt is made to perform an operation on a world in readonly mode, the code will throw an assert saying that the world is in readonly mode.
A call to ecs_readonly_begin() must be followed up with ecs_readonly_end(). When ecs_readonly_end() is called, all enqueued commands from configured stages are merged back into the world. Calls to ecs_readonly_begin() and ecs_readonly_end() should always happen from a context where the code has exclusive access to the world. The functions themselves are not thread-safe.
| world | The world. |
| multi_threaded | Whether to enable multithreaded readonly mode. |
| void ecs_readonly_end | ( | ecs_world_t * | world | ) |
End readonly mode.
This operation ends readonly mode, and must be called after ecs_readonly_begin(). Operations that were deferred while the world was in readonly mode will be flushed.
| world | The world. |
| void ecs_set_stage_count | ( | ecs_world_t * | world, |
| int32_t | stages ) |
Configure the world to have N stages.
This initializes N stages, which allows applications to defer operations to multiple isolated defer queues. This is typically used for applications with multiple threads, where each thread gets its own queue, and commands are merged when threads are synchronized.
Note that the ecs_set_threads() function already creates the appropriate number of stages. The ecs_set_stage_count() operation is useful for applications that want to manage their own stages and/or threads.
| world | The world. |
| stages | The number of stages. |
| void ecs_stage_free | ( | ecs_world_t * | stage | ) |
Free an unmanaged stage.
| stage | The stage to free. |
| int32_t ecs_stage_get_id | ( | const ecs_world_t * | world | ) |
Get the stage ID.
The stage ID can be used by an application to learn about which stage it is using, which typically corresponds with the worker thread ID.
| world | The world. |
| bool ecs_stage_is_readonly | ( | const ecs_world_t * | world | ) |
Test whether the current world is readonly.
This function allows the code to test whether the currently used world is readonly or whether it allows for writing.
| world | A pointer to a stage or the world. |
| ecs_world_t * ecs_stage_new | ( | ecs_world_t * | world | ) |
Create an unmanaged stage.
Create a stage whose lifecycle is not managed by the world. Must be freed with ecs_stage_free().
| world | The world. |