kata-containers/cgroups-rs
1
0
Fork 0
mirror of https://github.com/kata-containers/cgroups-rs.git synced 2026-08-05 02:13:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

builder: add some documentation

Browse Source 
Signed-off-by: Levente Kurusa <lkurusa@acm.org>
This commit is contained in:
Levente Kurusa
2018-10-13 22:34:27 +02:00
parent b4cc91f977
commit e51d781baf
1 changed files with 101 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
src/cgroup_builder.rs
View File

@@ -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,