Struct EcsApp

pub struct EcsApp<W, S = RandomState>
where
    W: Work + 'static,
    S: BuildHasher + Default + 'static,
{ /* private fields */ }

An ECS instance.

Clients can create the instance via Ecs::default, Ecs::create or EcsApp::new. It’s possible to have multiple ECS instances as well if you really need to do so, but it’s recommended to have multiple groups instead of multiple instances to reduce memory footprint and share data with ease.

• W - Worker type.
• S - Hasher builder type.

Implementations

impl<W, S> EcsApp<W, S>

where W: Work + 'static, S: BuildHasher + Default + 'static,

pub fn new(workers: Vec<W>, groups: &[usize]) -> Self

Creates an ECS instance with the given workers, group information, and hasher builder type.

Examples

use my_ecs::prelude::*;
use std::hash::{BuildHasher, DefaultHasher};

// Something like `std::hash::RandomState`.
#[derive(Default)]
struct FixedState;
impl BuildHasher for FixedState {
    type Hasher = DefaultHasher;
    fn build_hasher(&self) -> Self::Hasher {
        DefaultHasher::new()
    }
}

// Creates `EcsApp` with one group consisting of 4 workers.
let pool = WorkerPool::with_len(4);
let ecs: EcsApp<_, FixedState> = EcsApp::new(pool.into(), &[4]);

// Creates `EcsApp` with two groups consisting of 2 workers respectively.
let pool = WorkerPool::with_len(4);
let ecs: EcsApp<_, FixedState> = EcsApp::new(pool.into(), &[2, 2]);

pub fn destroy(self) -> Vec<W>

Destroys the ecs instance and returns workers.

pub fn collect_poisoned_systems(&mut self) -> Vec<PoisonedSystem>

Takes out poisoned systems so far.

Examples

use my_ecs::prelude::*;

let v = Ecs::default(WorkerPool::with_len(1), [1])
    .add_once_system(|| {
        panic!("panics on purpose");
    })
    .step()
    .collect_poisoned_systems();
assert_eq!(v.len(), 1);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of internal data structures as much as possible.

pub fn step(&mut self) -> &mut Self

Executes active systems of all groups once.

Generated commands during the execution will be completely consumed at the end of system execution.

Examples

use my_ecs::prelude::*;
use std::sync::{Arc, Mutex};

let cnt = Arc::new(Mutex::new(0));
let c_cnt = Arc::clone(&cnt);

Ecs::default(WorkerPool::new(), [])
    .add_system(move || {
        *c_cnt.lock().unwrap() += 1;
    })
    .step();
assert_eq!(*cnt.lock().unwrap(), 1);

pub fn run<F, R>(&mut self, handle_error: F) -> With<&mut Self, Vec<R>>

where F: FnMut(Box<dyn Error + Send + Sync + 'static>) -> R,

Executes active systems of all groups until their lifetime goes to zero.

Examples

use my_ecs::prelude::*;
use std::sync::{Arc, Mutex};

let cnt = Arc::new(Mutex::new(0));
let c_cnt = Arc::clone(&cnt);

Ecs::default(WorkerPool::new(), [])
    .add_system(
        SystemDesc::new()
            .with_activation(2, InsertPos::Back)
            .with_system(move || {
                *c_cnt.lock().unwrap() += 1;
            })
    )
    .run(|_| {});
assert_eq!(*cnt.lock().unwrap(), 2);

pub fn wait_for_idle(&mut self) -> &mut Self

Waits for ecs to be idle.

Ecs becomes idle when all group’s workers get closed.

pub fn is_completed(&self) -> bool

Determines whether ecs has been executed completely, so that it cannot do anything.

If all conditions below are met, then ecs is considered as completed.

• No active systems
• No uncompleted commands
• No open sub workers

Trait Implementations

impl<W, S> Debug for EcsApp<W, S>

where W: Work + 'static + Debug, S: BuildHasher + Default + 'static + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<W, S> Drop for EcsApp<W, S>

where W: Work + 'static, S: BuildHasher + Default + 'static,

fn drop(&mut self)

Executes the destructor for this type.

impl<W, S> EcsEntry for EcsApp<W, S>

where W: Work + 'static, S: BuildHasher + Default + 'static,

fn add_system<T, Sys>( &mut self, desc: T, ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<Sys>>>

where T: Into<SystemDesc<Sys>>, Sys: System,

Adds the given system.

fn add_once_system<T, Req, F>( &mut self, sys: T, ) -> WithResult<&mut Self, SystemId, EcsError<SystemDesc<FnOnceSystem<Req, F>>>>

where T: Into<FnOnceSystem<Req, F>>, FnOnceSystem<Req, F>: System,

Adds the given FnOnce system.

fn unregister_system( &mut self, sid: SystemId, ) -> WithResult<&mut Self, (), EcsError>

Unregisters an inactive system for the given system id.

fn activate_system( &mut self, target: SystemId, at: InsertPos, live: Tick, ) -> WithResult<&mut Self, (), EcsError>

Activates a system for the given system id if it’s not active.

fn inactivate_system( &mut self, sid: SystemId, ) -> WithResult<&mut Self, (), EcsError>

Inactivates a system for the given system id.

fn register_entity( &mut self, desc: EntityReg, ) -> WithResult<&mut Self, EntityIndex, EcsError>

Registers an entity type from the given descriptor.

fn unregister_entity<C>( &mut self, ) -> WithResult<&mut Self, Box<dyn ContainEntity>, EcsError>

where C: Components,

Unregisters an entity type.

fn add_entity<E>( &mut self, ei: EntityIndex, value: E, ) -> WithResult<&mut Self, EntityId, EcsError<E>>

where E: Entity,

Adds an entity.

fn remove_entity( &mut self, eid: EntityId, ) -> WithResult<&mut Self, (), EcsError>

Removes an entity.

fn add_resource<T>( &mut self, desc: T, ) -> WithResult<&mut Self, ResourceIndex, EcsError<ResourceDesc>>

where T: Into<ResourceDesc>,

Adds the given resource.

fn remove_resource<R>(&mut self) -> WithResult<&mut Self, Option<R>, EcsError>

where R: Resource,

Removes a resource from the given resource type.

fn get_resource<R>(&self) -> Option<&R>

where R: Resource,

Retrieves shared reference to a resource for the given resource type.

fn get_resource_mut<R>(&mut self) -> Option<&mut R>

where R: Resource,

Retrieves mutable reference to a resource for the given resource type.

fn get_resource_index<R>(&self) -> Option<ResourceIndex>

where R: Resource,

Returns resource index for the given resource type.

fn execute_commands<T>( &mut self, cmds: T, ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>

where T: HelpExecuteManyCommands,

Executes the given commands in order.

fn execute_command<F, R>( &mut self, f: F, ) -> WithResult<&mut Self, (), Box<dyn Error + Send + Sync + 'static>>

where F: FnOnce(Commander<'_>) -> R, R: Command,

Execute the given command.

fn errors(&mut self) -> Vec<Box<dyn Error + Send + Sync + 'static>>

Returns errors generated from commands or futures.

fn add_systems<T, Systems>( &mut self, descs: T, ) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManySystems<Systems>,

Adds the given systems.

fn add_once_systems<T, Once>( &mut self, descs: T, ) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManyOnce<Once>,

Adds the given FnOnce systems.

fn register_entity_of<T>( &mut self, ) -> WithResult<&mut Self, EntityIndex, EcsError>

where T: AsEntityReg,

Registers an entity type.

fn add_resources<T>(&mut self, descs: T) -> WithResult<&mut Self, (), EcsError>

where T: HelpAddManyResources,

Adds the given resources.

impl<W, S> From<EcsApp<W, S>> for LeakedEcsApp

where W: Work + 'static, S: BuildHasher + Default + 'static,

fn from(value: EcsApp<W, S>) -> Self

Converts to this type from the input type.

impl<W, S> Resource for EcsApp<W, S>

where EcsApp<W, S>: Send + 'static, W: Work + 'static, S: BuildHasher + Default + 'static,