Enum glommio::Placement

pub enum Placement {
    Unbound,
    Fenced(CpuSet),
    MaxSpread(Option<CpuSet>),
    MaxPack(Option<CpuSet>),
    Custom(Vec<CpuSet>),
}

Specifies a policy by which LocalExecutorPoolBuilder selects CPUs.

Placement is use to bind LocalExecutors to a set of CPUs via preconfigured policies designed to address a variety of use cases. The default is Unbound.

Example

Some Placements allow manually filtering available CPUs via a CpuSet, such as MaxSpread. The following would place shards on four CPUs (a.k.a. hyper-threads) that are on NUMA node 0 and have an even numbered package ID according to their CpuLocation. The selection aims to achieve a high degree of separation between the CPUs in terms of machine topology. Each LocalExecutor would be bound to a single CPU.

Note that if four CPUs are not available, the call to LocalExecutorPoolBuilder::on_all_shards would return an Err when using MaxSpread.

use glommio::{CpuSet, LocalExecutorPoolBuilder, Placement};

let cpus = CpuSet::online()
    .expect("Err: please file an issue with glommio")
    .filter(|l| l.numa_node == 0)
    .filter(|l| l.package % 2 == 0);

let handles = LocalExecutorPoolBuilder::new(4)
    .placement(Placement::MaxSpread(Some(cpus)))
    .on_all_shards(|| async move {
        // ... important stuff ...
    })
    .unwrap();

handles.join_all();

Variants

Unbound

For the Unbound variant, the LocalExecutors created by a LocalExecutorPoolBuilder are not bound to any CPU. This is the default placement.

Fenced(CpuSet)

The Fenced variant binds each LocalExecutor to the set of CPUs specified by CpuSet. With an unfiltered CPU set returned by CpuSet::online, this is similar to using Unbound with the distinction that bringing additional CPUs online will not allow the executors to run on the newly available CPUs. The Fenced variant allows the number of shards specified in LocalExecutorPoolBuilder::new to be greater than the number of CPUs as long as at least one CPU is included in CpuSet.

Errors

If the provided CpuSet contains no CPUs, a call to LocalExecutorPoolBuilder::on_all_shards will return Result:: Err.

MaxSpread(Option<CpuSet>)

Each LocalExecutor is pinned to a particular CpuLocation such that the set of all CPUs selected has a high degree of sepration. The selection proceeds from all CPUs that are online in a non-deterministic manner. The Option<CpuSet> parameter may be used to restrict the CpuSet from which CPUs are selected; specifying None is equivalent to using Some(CpuSet::online()?).

Errors

If the number of shards specified in LocalExecutorPoolBuilder::new is greater than the number of CPUs available, then a call to LocalExecutorPoolBuilder::on_all_shards will return Result:: Err.

MaxPack(Option<CpuSet>)

Each LocalExecutor is pinned to a particular CpuLocation such that the set of all CPUs selected has a low degree of sepration. The selection proceeds from all CPUs that are online in a non-deterministic manner. The Option<CpuSet> parameter may be used to restrict the CpuSet from which CPUs are selected; specifying None is equivalent to using Some(CpuSet::online()?).

Errors

If the number of shards specified in LocalExecutorPoolBuilder::new is greater than the number of CPUs available, then a call to LocalExecutorPoolBuilder::on_all_shards will return Result:: Err.

Custom(Vec<CpuSet>)

One LocalExecutor is bound to each of the CpuSets specified by Custom. The number of CpuSets in the Vec should match the number of shards requested from the pool builder.

Errors

LocalExecutorPoolBuilder::on_all_shards will return Result::Err if either of the follow is true:

• The length of the vector does not match the number of shards requested in LocalExecutorPoolBuilder::new.
• Any of the CpuSets is empty.

Trait Implementations

impl Debug for Placement

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

Formats the value using the given formatter.

impl Default for Placement

The default is Placement::Unbound

fn default() -> Self

Returns the “default value” for a type.