Transaction Permissions

Permissions are acquired by starting a transaction on an ECS instance. Each transaction is associated with a Lock object, which contains the specific permissions granted for the transaction. The permissions required for each API function depend on the operations performed within those functions.

StartTransaction(): A new transaction is started by providing the desired permissions as template arguments. You can use any combination of the following permission types: - Tecs::Read<Components...>: Grants read-only access to a list of component types. - Tecs::ReadAll: Grants read-only access to all existing components. - Tecs::Write<Components...>: Grants write access to a list of component types (existing components only). - Tecs::WriteAll: Grants write access to all existing components. - Tecs::AddRemove: Grants the ability to create and delete new entities and components.

Here is a list of which permissions are required for each API function:

1. Entity

   • Exists(), Existed(): Require read permission for the components being checked.
   • Has(), Had(): Require read permission for the components being checked.
   • Get(): Requires read permission for the component being retrieved. If write access is requested (by returning a non-const reference), write permission is also required.
   • GetPrevious(): Requires read permission for the component being retrieved.
   • Set(): Requires write permission for the component being modified or set.
   • Unset(): Requires Tecs::AddRemove permission to remove components from an entity.
   • Destroy(): Requires Tecs::AddRemove permission to destroy an entity.

2. Lock

   • is_lock_subset(): Determines if the lock can be constructed from a lock with specified source permissions.
   • has_permissions(): Determines if the lock has all the requested permissions.
   • PreviousEntitiesWith(), EntitiesWith(): Require read permission for the component type being queried.
   • PreviousEntities(), Entities(): Require read permission for all component types involved in the query.
   • NewEntity(): Requires Tecs::AddRemove permission to create a new entity.
   • Has(), Had(): Require read permission for the global components being checked.
   • Get(): Requires read permission for the global component being retrieved. If write access is requested (by returning a non-const reference), write permission is also required.
   • GetPrevious(): Requires read permission for the global component being retrieved.
   • Set(): Requires write permission for the global component being set or modified.
   • Unset(): Requires Tecs::AddRemove permission to remove global components.
   • Watch(): Requires Tecs::AddRemove permission to create an observer for ECS changes.
   • StopWatching(): Requires Tecs::AddRemove permission to stop an observer.

3. DynamicLock

   • TryLock(): Attempts to acquire a lock with the specified dynamic permissions. The required permissions depend on the requested dynamic permissions, which should be a subset of the static permissions of the DynamicLock. If the requested permissions are a subset of the static permissions, the function returns a new Lock object with the requested permissions. If not, the function returns an empty std::optional.

Remember that it is recommended to start transactions with the minimum required permissions to prevent unnecessary thread synchronization. This also helps to avoid potential deadlocks and ensures that your code is more efficient and safer in multi-threaded scenarios.