Struct JobScope

pub struct JobScope { /* private fields */ }

Manages the creation and scheduling of jobs. This type can either be created from a JobSystem instance or retrieved from a worker thread. If you tried to use this with a thread that is not being tracked by the job system, all the functions will fail with Error::InvalidThread.

Implementations

impl JobScope

pub fn new_from_system(job_system: &JobSystem) -> Self

Create a new instance from a job system.

pub fn new_from_thread() -> Result<Self, Error>

Create a new instance on a thread managed by a job system. If this calling thread is not managed by the job system, this will fail

pub fn create_noop(&self) -> Result<ScopedJobHandle<'_, fn()>, Error>

Allocates a new Job that does nothing.

This can be useful in cases where you need a parent job for grouping control.

pub unsafe fn create<T>(&self, job: T) -> Result<ScopedJobHandle<'_, T>, Error>

where T: Sized + FnOnce() + Send,

Allocate a new Job

This function will check whether the closure fits in the job storage space and return an error if that’s the case.

Safety

This function is unsafe since it’s not possible to accurately determine whether the provided closure’s capture will be captured multiple times or be alive until this closure has finished executing. This method is safe to call provided that you guarantee:

• The closure captures are valid during the execution of the job
• The closure doesn’t capture a writeable reference more than once

pub unsafe fn create_with_parent<'a, T, Y>( &'a self, parent: &ScopedJobHandle<'a, Y>, job: T, ) -> Result<ScopedJobHandle<'a, T>, Error>

where T: Sized + FnOnce() + Send,

Allocate a new Job as a child of another job.

The newly allocated will be created as a child of a parent job. What this means in practice is that the new job (child) can run parallel with the parent job and the parent job will not reach completion status until all of it’s children have finished.

Safety

This function is unsafe since it’s not possible to accurately determine whether the provided closure’s capture will be captured multiple times or be alive until this closure has finished executing. This method is safe to call provided that you guarantee:

• The closure captures are valid during the execution of the job
• The closure doesn’t capture a writeable reference more than once

pub fn chain<T, Y>( &self, parent: &mut ScopedJobHandle<'_, T>, child: &ScopedJobHandle<'_, Y>, ) -> Result<(), Error>

where T: Sized + FnOnce() + Send, Y: Sized + FnOnce() + Send,

Register the child job as a follow up to the parent job.

Every Job has the ability to chain follow up jobs on completion. This ensures the child job only runs when the parent is finished.

There is a limited capacity for the number of jobs you can chain with one job. This function will return error if we are unable to register the child job.

pub unsafe fn run<T>( &self, handle: &ScopedJobHandle<'_, T>, ) -> Result<(), Error>

where T: Sized + FnOnce() + Send,

Execute a job.

Safety

This is currently marked unsafe due to the reasons described in JobScope::create() and JobScope::create_with_parent().

pub fn wait<T>(&self, handle: &ScopedJobHandle<'_, T>) -> Result<(), Error>

where T: Sized + FnOnce() + Send,

Block and wait until the job has finished.

While we wait, the system will try to execute other jobs.

pub fn is_finished<T>( &self, handle: &ScopedJobHandle<'_, T>, ) -> Result<bool, Error>

where T: Sized + FnOnce() + Send,

Check if a job has finished execution. Does not block.

pub fn for_each<'env, T, Y>( &self, slice: &'env mut [Y], cb: T, ) -> Result<(), Error>

where T: Fn(&mut [Y], usize, usize) + 'env + Send + Sync, Y: Send,

Given a slice of data and read-only closure, divide the slice into unique sub-slices which are distributed to the worker threads.

The closure will receive the following parameters in order:

• unique sub-slice over which the the current thread is operating on
• start index of the full slice
• end index of the the full slice Note use for_each_with_result() if you wish to produce output.

pub fn for_each_with_result<'env, T, Y, Z>( &self, slice: &'env mut [Y], cb: T, ) -> Result<Vec<Z>, Error>

where T: Fn(&[Y], usize, usize) -> Z + 'env + Send + Sync, Z: Sized + Default + Send, Y: Send,

Same as for_each() but allows a result type to be returned for every individual group.

Trait Implementations

impl Debug for JobScope

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

Formats the value using the given formatter.