Struct employees::Runtime

source ·

pub struct Runtime { /* private fields */ }

Expand description

A runtime that manages Workers threads.

When dropped, a runtime stops and waits for all the workers to complete.

Implementations§

source §

impl Runtime

source

pub fn new() -> Self

Returns a new runtime.

source

pub fn enable_graceful_shutdown(&self)

Enables this runtime to be gracefully shutdown with a Ctrl+C signal.

If the gracefull shutdown doesn’t have any effects, users can still send a second Ctrl+C signal to forcefully kill the runtime.

source

pub fn nested(shutdown: Shutdown) -> Self

Returns a new runtime whose stopping condition is controlled by the “parent” runtime from which shutdown is originates.

This allows users to spawn runtimes in workers without caring about the shutdown.

source

pub fn launch<W: Worker + 'static>(&mut self, worker: W) -> Result<(), Error>

Runs a Worker in a new thread.

§Errors

On error, the corresponding error is returned and the runtime is stopped.

§Examples

struct Employee;
// -- skipping the Worker implementation for Employee...

let mut runtime = Runtime::new();

// Run a Employee thread.
runtime.launch(Employee).unwrap();

source

pub fn launch_with_settings<W: Worker + 'static>( &mut self, worker: W, settings: Settings, ) -> Result<(), Error>

Runs a Worker in a new thread.

The new thread will be configured with settings.

§Errors

On error, the corresponding error is returned and the runtime is stopped.

§Examples

struct Employee;
// -- skipping the Worker implementation for Employee...

let mut runtime = Runtime::new();
let settings = Settings::new().name("alice");

// Run a Employee thread named "alice".
runtime.launch_with_settings(Employee, settings).unwrap();

source

pub fn launch_pinned<W, C>(&mut self, worker: W, cores: C) -> Result<(), Error>
where W: Worker + 'static, C: AsRef<[usize]> + Send + 'static,

Runs a Worker in a new thread.

The new thread will have its affinity set to the cores.

§Errors

On error, the corresponding error is returned and the runtime is stopped.

§Examples

struct Employee;
// -- skipping the Worker implementation for Employee...

let mut runtime = Runtime::new();

// Run a Employee thread bound to the CPU #1.
runtime.launch_pinned(Employee, [1]).unwrap();

source

pub fn launch_pinned_with_settings<W, C>( &mut self, worker: W, cores: C, settings: Settings, ) -> Result<(), Error>
where W: Worker + 'static, C: AsRef<[usize]> + Send + 'static,

Runs a Worker in a new thread.

The new thread will be configured with settings and its affinity set to the cores.

§Errors

On error, the corresponding error is returned and the runtime is stopped.

§Examples

struct Employee;
// -- skipping the Worker implementation for Employee...

let mut runtime = Runtime::new();
let settings = Settings::new().name("alice");

// Run a Employee thread named "alice" bound to the CPU #1.
runtime.launch_pinned_with_settings(Employee, [1], settings).unwrap();

source

pub fn launch_from_context<W, C>(&mut self, ctx: C) -> Result<(), Error>
where W: Worker + 'static, C: Context<Target = W>,

Runs a Worker built from a Context in a new thread.

The new thread will be configured using the values returned by the Context::settings function and its affinity set using the Context::core_pinning function.

§Errors

On error, the corresponding error is returned and the runtime is stopped.

§Examples

struct Employee;
// -- skipping the Worker implementation for Employee...

struct EmployeeContext;
impl Context for EmployeeContext {
    // -- skipping the building of Employee...

    fn settings(&self) -> Settings {
        // Setting the thread name.
        Settings::default().name("employee")
    }

    fn core_pinning(&self) -> Option<Vec<usize>> {
        // Setting the thread affinity on the CPU #1.
        Some(vec![1])
    }
}

let mut runtime = Runtime::new();
runtime.launch_from_context(EmployeeContext).unwrap();

source

pub fn launch_respawnable<C>(&mut self, ctx: C) -> Result<(), Error>
where C: RespawnableContext<'static> + 'static,

Runs a Worker built from a RespawnableContext that can be respawned if it panics.

Similar to Runtime::launch_from_context, see its documentation for more details.

source

pub fn wait(&mut self)

Blocks the calling thread until all the runtime’s workers stop.

This function also takes care of respawning panicked workers launched using RespawnableContext. See the health_check for more details.

§Example

struct Employee;

impl Worker for Employee {
    fn on_update(&mut self) -> ControlFlow {
        // Let's simulate some work.
        std::thread::sleep(Duration::from_secs(1));

        ControlFlow::Break
    }
}

let mut runtime = Runtime::new();
let now = Instant::now();

runtime.launch(Employee).unwrap();
runtime.wait();

assert!(now.elapsed() >= Duration::from_secs(1));

source

pub fn health_check(&mut self)

Checks all respawnable Workers, respawning the ones that panicked.

Workers that finished but didn’t panic are simply dropped.

§Examples

// A worker that panic some time after being spawned...
struct PanickingWorker;
impl Worker for PanickingWorker {
    fn on_update(&mut self) -> ControlFlow {
        std::thread::sleep(Duration::from_secs(1));
        panic!("panicking!")
    }
}

// ... and its context.
struct WorkerContext;
impl RespawnableContext<'_> for WorkerContext {
    fn boxed_worker(&self) -> Result<Box<dyn Worker>, Error> {
        Ok(Box::new(PanickingWorker))
    }
}

let mut runtime = Runtime::new();
runtime.launch_respawnable(WorkerContext);

std::thread::sleep(Duration::from_secs(1));
runtime.health_check();