Struct glommio::LocalExecutorBuilder

pub struct LocalExecutorBuilder { /* private fields */ }

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::default();
let ex = builder.make().unwrap();

Implementations

impl LocalExecutorBuilder

pub fn new(placement: Placement) -> LocalExecutorBuilder

Generates the base configuration for spawning a LocalExecutor, from which configuration methods can be chained. The method’s only argument is the Placement policy by which the LocalExecutor is bound to the machine’s hardware topology. i.e. how many and which CPUs to use.

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 64 kiB for I/O memory, and the default is 10 MiB.

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

The depth of the IO rings to create. This influences the level of IO concurrency. A higher ring depth allows a shard to submit a greater number of IO requests to the kernel at once.

Values above zero are valid and the default is 128.

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 record_io_latencies(self, enabled: bool) -> LocalExecutorBuilder

Whether to record the latencies of individual IO requests as part of the IO stats. Recording latency can be expensive. Disabled by default.

pub fn blocking_thread_pool_placement( self, placement: PoolPlacement ) -> LocalExecutorBuilder

The placement policy of the blocking thread pool. Defaults to one thread using the same placement strategy as the host executor.

pub fn detect_stalls( self, handler: Option<Box<dyn StallDetectionHandler + 'static>> ) -> Self

Whether to detect stalls in unyielding tasks. stall::DefaultStallDetectionHandler installs a signal handler for nix::libc::SIGUSR1, so is disabled by default.

Examples

use glommio::{DefaultStallDetectionHandler, LocalExecutorBuilder};

let local_ex = LocalExecutorBuilder::default()
    .detect_stalls(Some(Box::new(DefaultStallDetectionHandler {})))
    .make()
    .unwrap();

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::default().make().unwrap();

pub fn spawn<G, F, T>(self, fut_gen: G) -> Result<ExecutorJoinHandle<T>, ()>

where G: FnOnce() -> F + Send + 'static, F: Future<Output = T> + 'static, T: Send + '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::default()
    .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.