Struct Workload 

pub struct Workload { /* private fields */ }

Keeps information to create a workload.

A workload is a collection of systems. They will execute as much in parallel as possible.
They are evaluated first to last when they can’t be parallelized.
The default workload will automatically be set to the first workload added.

Implementations

impl Workload

pub fn new<T>(label: impl AsLabel<T>) -> Self

Creates a new empty Workload.

Example

use shipyard::{Component, IntoIter, View, ViewMut, Workload, World};

#[derive(Component, Clone, Copy)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

fn add(mut usizes: ViewMut<USIZE>, u32s: View<U32>) {
    for (mut x, &y) in (&mut usizes, &u32s).iter() {
        x.0 += y.0 as usize;
    }
}

fn check(usizes: View<USIZE>) {
    let mut iter = usizes.iter();
    assert_eq!(iter.next(), Some(&USIZE(1)));
    assert_eq!(iter.next(), Some(&USIZE(5)));
    assert_eq!(iter.next(), Some(&USIZE(9)));
}

let mut world = World::new();

world.add_entity((USIZE(0), U32(1)));
world.add_entity((USIZE(2), U32(3)));
world.add_entity((USIZE(4), U32(5)));

Workload::new("Add & Check")
    .with_system(add)
    .with_system(check)
    .add_to_world(&world)
    .unwrap();

world.run_default_workload();

pub fn append(self, other: &mut Self) -> Self

Moves all systems of other into Self, leaving other empty.
This allows us to collect systems in different builders before joining them together.

pub fn merge(self, other: Workload) -> Workload

Propagates all information from self and other into their respective systems before merging their systems.
This includes run_if/skip_if, tags, before/after requirements.

pub fn with_workload(self, other: Workload) -> Workload

Propagates all information from self and other into their respective systems before merging their systems.
This includes run_if/skip_if, tags, before/after requirements.

pub fn with_system<B, R, S: IntoWorkloadSystem<B, R>>( self, system: S, ) -> Workload

Adds a system to the workload being created.

Example:

use shipyard::{Component, EntitiesViewMut, IntoIter, View, ViewMut, Workload, World};

#[derive(Component, Clone, Copy)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

fn add(mut usizes: ViewMut<USIZE>, u32s: View<U32>) {
    for (mut x, &y) in (&mut usizes, &u32s).iter() {
        x.0 += y.0 as usize;
    }
}

fn check(usizes: View<USIZE>) {
    let mut iter = usizes.iter();
    assert_eq!(iter.next(), Some(&USIZE(1)));
    assert_eq!(iter.next(), Some(&USIZE(5)));
    assert_eq!(iter.next(), Some(&USIZE(9)));
}

let mut world = World::new();

world.add_entity((USIZE(0), U32(1)));
world.add_entity((USIZE(2), U32(3)));
world.add_entity((USIZE(4), U32(5)));

Workload::new("Add & Check")
    .with_system(add)
    .with_system(check)
    .add_to_world(&world)
    .unwrap();

world.run_default_workload();

pub fn with_try_system<B, Ok, Err: 'static + Into<Box<dyn Error + Send + Sync>>, R: Into<Result<Ok, Err>>, S: IntoWorkloadTrySystem<B, R>>( self, system: S, ) -> Self

Adds a fallible system to the workload being created.
The workload’s execution will stop if any error is encountered.

Example:

use shipyard::{Component, EntitiesViewMut, Get, IntoIter, View, ViewMut, Workload, World};
use shipyard::error::MissingComponent;

#[derive(Component, Clone, Copy)]
struct U32(u32);

#[derive(Component, Debug, PartialEq, Eq)]
struct USIZE(usize);

fn add(mut usizes: ViewMut<USIZE>, u32s: View<U32>) {
    for (mut x, &y) in (&mut usizes, &u32s).iter() {
        x.0 += y.0 as usize;
    }
}

fn check(usizes: View<USIZE>) -> Result<(), MissingComponent> {
    for (id, i) in usizes.iter().with_id() {
        assert!(usizes.get(id)? == i);
    }

    Ok(())
}

let mut world = World::new();

world.add_entity((USIZE(0), U32(1)));
world.add_entity((USIZE(2), U32(3)));
world.add_entity((USIZE(4), U32(5)));

Workload::new("Add & Check")
    .with_system(add)
    .with_try_system(check)
    .add_to_world(&world)
    .unwrap();

world.run_default_workload();

pub fn add_to_world(self, world: &World) -> Result<(), AddWorkload>

Finishes the workload creation and stores it in the World.
Returns a struct with describing how the workload has been split in batches.

Borrows

• Scheduler (exclusive)
• AllStorages (shared)
• Systems’ storage (exclusive) to enable tracking

Errors

• Scheduler borrow failed.
• Workload with an identical name already present.
• Nested workload is not present in world.
• AllStorages borrow failed.
• Storage borrow failed.

pub fn are_all_uniques_present_in_world( &self, world: &World, ) -> Result<(), UniquePresence>

Returns the first Unique storage borrowed by this workload that is not present in world.
If the workload contains nested workloads they have to be present in the World.

Borrows

• AllStorages (shared)

pub fn build(self) -> Result<(ScheduledWorkload, WorkloadInfo), AddWorkload>

Build the Workload from the Workload.

pub fn with_barrier(self) -> Self

Stop parallelism between systems before and after the barrier.

Trait Implementations

impl Extend<WorkloadSystem> for Workload

fn extend<T: IntoIterator<Item = WorkloadSystem>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl IntoWorkload<Workload, Workload> for Workload

fn into_workload(self) -> Workload

Converts to a collection of systems.

fn into_sequential_workload(self) -> Workload

Converts to a collection of systems.
All systems will run one after the other. Does not propagate into nested Workload but they will run sequentially between them.

impl WorkloadModificator for Workload

fn run_if<RunB, Run: IntoWorkloadRunIf<RunB>>(self, run_if: Run) -> Workload

Only run the workload if the function evaluates to true.

fn run_if_storage_empty<T: Component>(self) -> Workload

Only run the workload if the T storage is empty.

fn run_if_missing_unique<T: Unique>(self) -> Workload

Only run the workload if the T unique storage is not present in the World.

fn run_if_storage_empty_by_id(self, storage_id: StorageId) -> Workload

Only run the workload if the storage is empty.

fn skip_if<RunB, Run: IntoWorkloadRunIf<RunB>>(self, should_skip: Run) -> Self

Do not run the workload if the function evaluates to true.

fn skip_if_storage_empty<T: Component>(self) -> Self

Do not run the workload if the T storage is empty.

fn skip_if_missing_unique<T: Unique>(self) -> Self

Do not run the workload if the T unique storage is not present in the World.

fn skip_if_storage_empty_by_id(self, storage_id: StorageId) -> Self

Do not run the workload if the storage is empty.

fn before_all<T>(self, other: impl AsLabel<T>) -> Workload

When building a workload, all systems within this workload will be placed before all invocation of the other system or workload.

fn after_all<T>(self, other: impl AsLabel<T>) -> Workload

When building a workload, all systems within this workload will be placed after all invocation of the other system or workload.

fn rename<T>(self, name: impl AsLabel<T>) -> Workload

Changes the name of this workload.

fn tag<T>(self, tag: impl AsLabel<T>) -> Workload

Adds a tag to this workload. Tags can be used to control system ordering when running workloads.