From e51d781baf471d1303fbbceaaa40d5d73b7a470e Mon Sep 17 00:00:00 2001 From: Levente Kurusa Date: Sat, 13 Oct 2018 22:34:27 +0200 Subject: [PATCH] builder: add some documentation Signed-off-by: Levente Kurusa --- src/cgroup_builder.rs | 163 ++++++++++++++++++++++++++---------------- 1 file changed, 101 insertions(+), 62 deletions(-) diff --git a/src/cgroup_builder.rs b/src/cgroup_builder.rs index d37a036..1411bf8 100644 --- a/src/cgroup_builder.rs +++ b/src/cgroup_builder.rs @@ -1,48 +1,65 @@ //! This module allows the user to create a control group using the Builder pattern. +//! # Example +//! +//! The following example demonstrates how the control group builder looks like. The user +//! specifies the name of the control group (here: "hello") and the hierarchy it belongs to (here: +//! a V1 hierarchy). Next, the user selects a subsystem by calling functions like `memory()`, +//! `cpu()` and `devices()`. The user can then add restrictions and details via subsystem-specific +//! calls. To finalize a subsystem, the user may call `done()`. Finally, if the control group build +//! is done and all requirements/restrictions have been specified, the control group can be created +//! by a call to `build()`. +//! +//! ```rust,no_run +//! # use cgroups::*; +//! # use cgroups::devices::*; +//! # use cgroups::cgroup_builder::*; +//! let v1 = cgroups::hierarchies::V1::new(); +//! let cgroup: Cgroup = CgroupBuilder::new("hello", &v1) +//! .memory() +//! .kernel_memory_limit(1024 * 1024) +//! .memory_hard_limit(1024 * 1024) +//! .done() +//! .cpu() +//! .shares(100) +//! .done() +//! .devices() +//! .device(1000, 10, DeviceType::Block, true, +//! vec![DevicePermissions::Read, +//! DevicePermissions::Write, +//! DevicePermissions::MkNod]) +//! .device(6, 1, DeviceType::Char, false, vec![]) +//! .done() +//! .network() +//! .class_id(1337) +//! .priority("eth0".to_string(), 100) +//! .priority("wl0".to_string(), 200) +//! .done() +//! .hugepages() +//! .limit("2M".to_string(), 0) +//! .limit("4M".to_string(), 4 * 1024 * 1024 * 100) +//! .limit("2G".to_string(), 2 * 1024 * 1024 * 1024) +//! .done() +//! .blkio() +//! .weight(123) +//! .leaf_weight(99) +//! .weight_device(6, 1, 100, 55) +//! .weight_device(6, 1, 100, 55) +//! .throttle_iops() +//! .read(6, 1, 10) +//! .write(11, 1, 100) +//! .throttle_bps() +//! .read(6, 1, 10) +//! .write(11, 1, 100) +//! .done() +//! .build(); +//! ``` use error::*; use {pid, BlkIoDeviceResource, BlkIoDeviceThrottleResource, Cgroup, DeviceResource, Hierarchy, HugePageResource, NetworkPriority, Resources}; -// let cgroup: Cgroup = CgroupBuilder::new("hello", V1) -// .memory() -// .kernel_memory_limit(1024 * 1024) -// .memory_hard_limit(1024 * 1024) -// .done() -// .cpu() -// .shares(100) -// .done() -// .devices() -// .device(1000, 10, DeviceType::Block, true, -// vec![Read, Write, MkNod] -// .device(6, 1, DeviceType::Char, false, vec![]) -// .done() -// .network() -// .class_id(1337) -// .priority("eth0", 100) -// .priority("wl0", 200) -// .done() -// .hugepages() -// .limit("2M", 0) -// .limit("4M", 4 * 1024 * 1024 * 100) -// .limit("2G", 2 * 1024 * 1024 * 1024) -// .blkio() -// .weight(123) -// .leaf_weight(99) -// .weight_device(6, 1, 100, 55) -// .weight_device(6, 1, 100, 55) -// .throttle_iops() -// .read(6, 1, 10) -// .write(11, 1, 100) -// .throttle_bps() -// .read(6, 1, 10) -// .write(11, 1, 100) -// .done() -// .build(); -// - - macro_rules! gen_setter { - ($res:ident, $name:ident, $ty:ty) => { + ($res:ident, $cont:ident, $func:ident, $name:ident, $ty:ty) => { + /// See the similarly named function in the respective controller. pub fn $name(mut self, $name: $ty) -> Self { self.cgroup.resources.$res.update_values = true; self.cgroup.resources.$res.$name = $name; @@ -51,15 +68,12 @@ macro_rules! gen_setter { } } -/// A control group builder instance: -/// -/// # Example -/// Bla bla. TODO. +/// A control group builder instance pub struct CgroupBuilder<'a> { name: String, hierarchy: &'a Hierarchy, /// Internal, unsupported field: use the associated builders instead. - resources: Resources, // XXX: this should not be public. + resources: Resources, } impl<'a> CgroupBuilder<'a> { @@ -74,42 +88,51 @@ impl<'a> CgroupBuilder<'a> { } } + /// Builds the memory resources of the control group. pub fn memory(self) -> MemoryResourceBuilder<'a> { MemoryResourceBuilder { cgroup: self, } } + /// Builds the pid resources of the control group. pub fn pid(self) -> PidResourceBuilder<'a> { PidResourceBuilder { cgroup: self, } } + /// Builds the cpu resources of the control group. pub fn cpu(self) -> CpuResourceBuilder<'a> { CpuResourceBuilder { cgroup: self, } } + /// Builds the devices resources of the control group, disallowing or + /// allowing access to certain devices in the system. pub fn devices(self) -> DeviceResourceBuilder<'a> { DeviceResourceBuilder { cgroup: self, } } + /// Builds the network resources of the control group, setting class id, or + /// various priorities on networking interfaces. pub fn network(self) -> NetworkResourceBuilder<'a> { NetworkResourceBuilder { cgroup: self, } } + /// Builds the hugepage/hugetlb resources available to the control group. pub fn hugepages(self) -> HugepagesResourceBuilder<'a> { HugepagesResourceBuilder { cgroup: self, } } + /// Builds the block I/O resources available for the control group. pub fn blkio(self) -> BlkIoResourcesBuilder<'a> { BlkIoResourcesBuilder { cgroup: self, @@ -117,7 +140,7 @@ impl<'a> CgroupBuilder<'a> { } } - // Finalize the control group, consuming the builder and creating the control group. + /// Finalize the control group, consuming the builder and creating the control group. pub fn build(self) -> Cgroup<'a> { let cg = Cgroup::new(self.hierarchy, self.name); cg.apply(&self.resources); @@ -125,62 +148,70 @@ impl<'a> CgroupBuilder<'a> { } } +/// A builder that configures the memory controller of a control group. pub struct MemoryResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> MemoryResourceBuilder<'a> { - gen_setter!(memory, kernel_memory_limit, u64); - gen_setter!(memory, memory_hard_limit, u64); - gen_setter!(memory, memory_soft_limit, u64); - gen_setter!(memory, kernel_tcp_memory_limit, u64); - gen_setter!(memory, memory_swap_limit, u64); - gen_setter!(memory, swappiness, u64); + gen_setter!(memory, MemController, set_kmem_limit, kernel_memory_limit, u64); + gen_setter!(memory, MemController, set_limit, memory_hard_limit, u64); + gen_setter!(memory, MemController, set_soft_limit, memory_soft_limit, u64); + gen_setter!(memory, MemController, set_tcp_limit, kernel_tcp_memory_limit, u64); + gen_setter!(memory, MemController, set_memswap_limit, memory_swap_limit, u64); + gen_setter!(memory, MemController, set_swappiness, swappiness, u64); + /// Finish the construction of the memory resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } } +/// A builder that configures the pid controller of a control group. pub struct PidResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> PidResourceBuilder<'a> { - gen_setter!(pid, maximum_number_of_processes, pid::PidMax); + gen_setter!(pid, PidController, set_pid_max, maximum_number_of_processes, pid::PidMax); + /// Finish the construction of the pid resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } } +/// A builder that configures the cpuset & cpu controllers of a control group. pub struct CpuResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> CpuResourceBuilder<'a> { - gen_setter!(cpu, cpus, String); - gen_setter!(cpu, mems, String); - gen_setter!(cpu, shares, u64); - gen_setter!(cpu, quota, i64); - gen_setter!(cpu, period, u64); - gen_setter!(cpu, realtime_runtime, i64); - gen_setter!(cpu, realtime_period, u64); + gen_setter!(cpu, CpuSetController, set_cpus, cpus, String); + gen_setter!(cpu, CpuSetController, set_mems, mems, String); + gen_setter!(cpu, CpuController, set_shares, shares, u64); + gen_setter!(cpu, CpuController, set_cfs_quota, quota, i64); + gen_setter!(cpu, CpuController, set_cfs_period, period, u64); + gen_setter!(cpu, CpuController, set_rt_runtime, realtime_runtime, i64); + gen_setter!(cpu, CpuController, set_rt_period, realtime_period, u64); + /// Finish the construction of the cpu resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } } +/// A builder that configures the devices controller of a control group. pub struct DeviceResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> DeviceResourceBuilder<'a> { + /// Restrict (or allow) a device to the tasks inside the control group. pub fn device(mut self, major: i64, minor: i64, @@ -199,19 +230,23 @@ impl<'a> DeviceResourceBuilder<'a> { self } + /// Finish the construction of the devices resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } } +/// A builder that configures the net_cls & net_prio controllers of a control group. pub struct NetworkResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> NetworkResourceBuilder<'a> { - gen_setter!(network, class_id, u64); + gen_setter!(network, NetclsController, set_class, class_id, u64); + /// Set the priority of the tasks when operating on a networking device defined by `name` to be + /// `priority`. pub fn priority(mut self, name: String, priority: u64) -> NetworkResourceBuilder<'a> { self.cgroup.resources.network.update_values = true; @@ -222,17 +257,20 @@ impl<'a> NetworkResourceBuilder<'a> { self } + /// Finish the construction of the network resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } } +/// A builder that configures the hugepages controller of a control group. pub struct HugepagesResourceBuilder<'a> { cgroup: CgroupBuilder<'a>, } impl<'a> HugepagesResourceBuilder<'a> { + /// Limit the usage of certain hugepages (determined by `size`) to be at most `limit` bytes. pub fn limit(mut self, size: String, limit: u64) -> HugepagesResourceBuilder<'a> { self.cgroup.resources.hugepages.update_values = true; @@ -243,6 +281,7 @@ impl<'a> HugepagesResourceBuilder<'a> { self } + /// Finish the construction of the network resources of a control group. pub fn done(self) -> CgroupBuilder<'a> { self.cgroup } @@ -255,8 +294,8 @@ pub struct BlkIoResourcesBuilder<'a> { impl<'a> BlkIoResourcesBuilder<'a> { - gen_setter!(blkio, weight, u16); - gen_setter!(blkio, leaf_weight, u16); + gen_setter!(blkio, BlkIoController, set_weight, weight, u16); + gen_setter!(blkio, BlkIoController, set_leaf_weight, leaf_weight, u16); pub fn weight_device(mut self, major: u64,