diff --git a/src/cgroup.rs b/src/cgroup.rs index 809a198..389208c 100644 --- a/src/cgroup.rs +++ b/src/cgroup.rs @@ -50,10 +50,17 @@ impl Cgroup { cg } + /// The list of subsystems that this control group supports. pub fn subsystems(self: &Self) -> &Vec { &self.subsystems } + /// Deletes the control group. + /// + /// Note that this function makes no effort in cleaning up the descendant and the underlying + /// system call will fail if there are any descendants. Thus, one should check whether it was + /// actually removed, and remove the descendants first if not. In the future, this behavior + /// will change. pub fn delete(self: Self) { self.subsystems.into_iter().for_each(|sub| { match sub { @@ -74,12 +81,23 @@ impl Cgroup { }); } + /// Apply a set of resource limits to the control group. pub fn apply(self: &Self, res: &Resources) { for subsystem in &self.subsystems { subsystem.to_controller().apply(res); } } + /// Retrieve a container based on type inference. + /// + /// ## Example: + /// + /// ``` + /// let pids: &PidController = control_group.controller_of() + /// .expect("No pids controller attached!"); + /// let cpu: &CpuController = control_group.controller_of() + /// .expect("No cpu controller attached!"); + /// ``` pub fn controller_of<'a, T>(self: &'a Self) -> Option<&'a T> where &'a T: From<&'a Subsystem>, T: Controller + ControllIdentifier, @@ -96,6 +114,7 @@ impl Cgroup { None } + /// Attach a task to the control group. pub fn add_task(self: &Self, pid: CgroupPid) { self.subsystems().iter().for_each(|sub| sub.to_controller().add_task(&pid)); } diff --git a/src/hierarchies.rs b/src/hierarchies.rs index 86a86d1..832443b 100644 --- a/src/hierarchies.rs +++ b/src/hierarchies.rs @@ -1,3 +1,8 @@ +//! This module represents the various control group hierarchies the Linux kernel supports. +//! +//! Currently, we only support the cgroupv1 hierarchy, but in the future we will add support for +//! the Unified Hierarchy. + use std::io::BufRead; use std::io::BufReader; use std::fs::File; @@ -18,6 +23,8 @@ use ::net_prio::NetPrioController; use ::hugetlb::HugeTlbController; use ::rdma::RdmaController; + +/// The standard, original cgroup implementation. Often referred to as "cgroupv1". pub struct V1 { mount_point: String, } @@ -83,17 +90,11 @@ impl Hierarchy for V1 { fn root(self: &Self) -> PathBuf { PathBuf::from(self.mount_point.clone()) } - - fn can_create_cgroup(self: &Self) -> bool { - /* - * V1 hierarchies do not support creating cgroups, - * they have to be created in a subsystem - */ - false - } } impl V1 { + /// Finds where control groups are mounted to and returns a hierarchy in which control groups + /// can be created. pub fn new() -> Self { let mount_point = find_v1_mount().unwrap(); V1 { diff --git a/src/lib.rs b/src/lib.rs index 02b85a8..363c253 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -184,9 +184,13 @@ pub trait ControllIdentifier { /// Control group hierarchy (right now, only V1 is supported, but in the future Unified will be /// implemented as well). pub trait Hierarchy { + /// Returns what subsystems are supported by the hierarchy. fn subsystems(self: &Self) -> Vec; - fn can_create_cgroup(self: &Self) -> bool; + /// Returns the root directory of the hierarchy. fn root(self: &Self) -> PathBuf; + /// Checks whether a certain subsystem is supported in the hierarchy. + /// + /// This is an internal function and should not be used. fn check_support(self: &Self, sub: Controllers) -> bool; } @@ -299,7 +303,10 @@ pub struct Resources { pub blkio: BlkIoResources, } +/// A structure representing a `pid`. Currently implementations exist for `u64` and +/// `std::process::Child`. pub struct CgroupPid { + /// The process identifier pub pid: u64, }