Struct controlgroup::v1::builder::Builder

pub struct Builder { /* fields omitted */ }

Cgroup builder.

By using Builder, you can configure a (set of) cgroup(s) in the builder pattern. This builder creates directories for the cgroups, but only for the configured subsystems. e.g. If you call only cpu method, only one cgroup directory is created for the CPU subsystem.

use std::path::PathBuf;
use controlgroup::{Max, v1::{devices, hugetlb, net_cls, rdma, Builder, SubsystemKind}};

let mut cgroups =
    // Start building a (set of) cgroup(s).
    Builder::new(PathBuf::from("students/charlie"))
    // Start configuring the CPU resource limits.
    .cpu()
        .shares(1000)
        .cfs_quota_us(500 * 1000)
        .cfs_period_us(1000 * 1000)
        // Finish configuring the CPU resource limits.
        .done()
    // Start configuring the cpuset resource limits.
    .cpuset()
        .cpus([0].iter().copied().collect())
        .mems([0].iter().copied().collect())
        .memory_migrate(true)
        .done()
    .memory()
        .limit_in_bytes(4 * (1 << 30))
        .soft_limit_in_bytes(3 * (1 << 30))
        .use_hierarchy(true)
        .done()
    .hugetlb()
        .limit_2mb(hugetlb::Limit::Pages(4))
        .limit_1gb(hugetlb::Limit::Pages(2))
        .done()
    .devices()
        .deny(vec!["a *:* rwm".parse::<devices::Access>().unwrap()])
        .allow(vec!["c 1:3 mr".parse::<devices::Access>().unwrap()])
        .done()
    .blkio()
        .weight(1000)
        .weight_device([([8, 0].into(), 100)].iter().copied())
        .read_bps_device([([8, 0].into(), 10 * (1 << 20))].iter().copied())
        .write_iops_device([([8, 0].into(), 100)].iter().copied())
        .done()
    .rdma()
        .max(
            [(
                "mlx4_0".to_string(),
                rdma::Limit {
                    hca_handle: 2.into(),
                    hca_object: Max::Max,
                },
            )].iter().cloned(),
        )
        .done()
    .net_prio()
        .ifpriomap(
            [("lo".to_string(), 0), ("wlp1s0".to_string(), 1)].iter().cloned(),
        )
        .done()
    .net_cls()
        .classid([0x10, 0x1].into())
        .done()
    .pids()
        .max(42.into())
        .done()
    .freezer()
        // Tasks in this cgroup will be frozen.
        .freeze()
        .done()
    // Enable CPU accounting for this cgroup.
    // Cpuacct subsystem has no parameter, so this method does not return a subsystem builder,
    // just enables the accounting.
    .cpuacct()
    // Enable monitoring this cgroup via `perf` tool.
    // Like `cpuacct()` method, this method does not return a subsystem builder.
    .perf_event()
    // Skip creating directories for Cpuacct subsystem and net_cls subsystem.
    // This is useful when some subsystems share hierarchy with others.
    .skip_create(vec![SubsystemKind::Cpuacct, SubsystemKind::NetCls])
    // Actually build cgroups with the configuration.
    .build()?;

let pid = std::process::id().into();
cgroups.add_task(pid)?;

// Do something ...

cgroups.remove_task(pid)?;
cgroups.delete()?;

Note that calling the same method of the same subsystem builder twice overrides the previous configuration if set.

let mut cgroups = Builder::new(PathBuf::from("students/charlie"))
    .cpu()
        .shares(1000)
        .shares(2000)   // Override.
        .done()
    .build()?;

assert_eq!(cgroups.cpu().unwrap().shares()?, 2000);

But building the same subsystem twice does not reset the subsystem configuration.

let mut cgroups = Builder::new(PathBuf::from("students/charlie"))
    .cpu()
        .shares(1000)
        .done()
    .cpu()  // Not reset shares.
        .cfs_quota_us(500 * 1000)
        .cfs_period_us(1000 * 1000)
        .done()
    .build()?;

assert_eq!(cgroups.cpu().unwrap().shares()?, 1000);

Methods

impl Builder

pub fn new(name: PathBuf) -> Self

Creates a new cgroup builder.

The resulting (set of) cgroup(s) will have the given name. For the directory name of each subsystem, the standard name (e.g. cpu for the CPU subsystem) is used.

pub fn skip_create(
    self,
    skip_subsystems: impl IntoIterator<Item = SubsystemKind>
) -> Self

Skips creating and deleting the directories for some subsystems.

This method is useful when multiple subsystems share the same hierarchy (including via symbolic links), and thus build method tries to create the same directory multiple times.

pub fn cpu(self) -> CpuBuilder

Starts configuring the CPU subsystem.

pub fn cpuset(self) -> CpusetBuilder

Starts configuring the cpuset subsystem.

pub fn memory(self) -> MemoryBuilder

Starts configuring the memory subsystem.

pub fn hugetlb(self) -> HugeTlbBuilder

Starts configuring the hugetlb subsystem.

pub fn devices(self) -> DevicesBuilder

Starts configuring the devices subsystem.

pub fn blkio(self) -> BlkIoBuilder

Starts configuring the blkio subsystem.

pub fn rdma(self) -> RdmaBuilder

Starts configuring the RDMA subsystem.

pub fn net_prio(self) -> NetPrioBuilder

Starts configuring the net_prio subsystem.

pub fn net_cls(self) -> NetClsBuilder

Starts configuring the net_cls subsystem.

pub fn pids(self) -> PidsBuilder

Starts configuring the pids subsystem.

pub fn freezer(self) -> FreezerBuilder

Starts configuring the freezer subsystem.

pub fn cpuacct(self) -> Self

Enables CPU accounting for this cgroup.

pub fn perf_event(self) -> Self

Enables monitoring this cgroup via perf tool.

pub fn build(self) -> Result<UnifiedRepr>

Builds a (set of) cgroup(s) with the configuration.

This method creates directories for the cgroups, but only for the configured subsystems. i.e. if you called only cpu method, only one cgroup directory is created for the CPU subsystem.

Also, this method does not create subsystems that are skipped by skip_create method.

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.