Struct glommio::LocalExecutorBuilder

pub struct LocalExecutorBuilder { /* fields omitted */ }

A factory that can be used to configure and create a LocalExecutor.

Methods can be chained on it in order to configure it.

The spawn method will take ownership of the builder and create a Result to the LocalExecutor handle with the given configuration.

The LocalExecutor::default free function uses a Builder with default configuration and unwraps its return value.

You may want to use LocalExecutorBuilder::spawn instead of LocalExecutor::default, when you want to recover from a failure to launch a thread. The LocalExecutor::default function will panic where the Builder method will return a io::Result.

Examples

use glommio::LocalExecutorBuilder;

let builder = LocalExecutorBuilder::new();
let ex = builder.make().unwrap();

Implementations

impl LocalExecutorBuilder

pub fn new() -> LocalExecutorBuilder

Generates the base configuration for spawning a LocalExecutor, from which configuration methods can be chained.

pub fn pin_to_cpu(self, cpu: usize) -> LocalExecutorBuilder

Sets the new executor’s affinity to the provided CPU. The largest cpu value supported by libc is 1023.

pub fn spin_before_park(self, spin: Duration) -> LocalExecutorBuilder

Spin for duration before parking a reactor

pub fn name(self, name: &str) -> LocalExecutorBuilder

Names the thread-to-be. Currently the name is used for identification only in panic messages.

pub fn io_memory(self, io_memory: usize) -> LocalExecutorBuilder

Amount of memory to reserve for storage I/O. This will be preallocated and registered with io_uring. It is still possible to use more than that but it will come from the standard allocator and performance will suffer.

The system will always try to allocate at least 64kB for I/O memory, and the default is 10MB.

pub fn preempt_timer(self, dur: Duration) -> LocalExecutorBuilder

How often need_preempt will return true by default.

Lower values mean task queues will switch execution more often, which can help latency but harm throughput. When individual task queues are present, this value can still be dynamically lowered through the Latency setting.

Default is 100ms.

pub fn make(self) -> Result<LocalExecutor, ()>

Make a new LocalExecutor by taking ownership of the Builder, and returns a Result to the executor.

Examples

use glommio::LocalExecutorBuilder;

let local_ex = LocalExecutorBuilder::new().make().unwrap();

#[must_use = "This spawns an executor on a thread, so you may need to call \ `JoinHandle::join()` to keep the main thread alive"]

pub fn spawn<G, F, T>(self, fut_gen: G) -> Result<JoinHandle<()>, ()> where
    G: FnOnce() -> F + Send + 'static,
    F: Future<Output = T> + 'static, 

Spawn a new LocalExecutor in a new thread with a given task.

This spawn function is an ergonomic shortcut for calling std::thread::spawn, LocalExecutorBuilder::make in the spawned thread, and then LocalExecutor::run. This spawn function takes ownership of a LocalExecutorBuilder with the configuration for the LocalExecutor, spawns that executor in a new thread, and starts the task given by fut_gen() in that thread.

The indirection of fut_gen() here (instead of taking a Future) allows for futures that may not be Send-able once started. As this executor is thread-local, it can guarantee that the futures will not be Sent once started.

Panics

The newly spawned thread panics if creating the executor fails. If you need more fine-grained error handling consider initializing those entities manually.

Example

use glommio::LocalExecutorBuilder;

let handle = LocalExecutorBuilder::new()
    .spawn(|| async move {
        println!("hello");
    })
    .unwrap();

handle.join().unwrap();

Trait Implementations

impl Debug for LocalExecutorBuilder

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

Formats the value using the given formatter.

impl Default for LocalExecutorBuilder

fn default() -> Self

Returns the “default value” for a type.