Introduce libcgroup examples and README updates

Signed-off-by: Kris Nóva <kris@nivenly.com>

crates/libcgroups/Cargo.toml

@@ -42,3 +42,11 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 env_logger = "0.10"
 serial_test = "0.10.0"
+
+[[example]]
+name = "bpf"
+path = "examples/bpf.rs"
+
+[[example]]
+name = "create"
+path = "examples/create.rs"

crates/libcgroups/README.md

@@ -1 +1,48 @@
 # libcgroups
+
+Youki crate for creating and managing cgroups.
+
+By default, youki will determine which cgroup hierarchy to use based on the state of the system at runtime.
+
+The cgroup implementation uses a public trait called `CgroupManager` which can be an implementation of:
+
+ - Cgroup v1 hierarchy
+ - Cgroup v2 hierarchy
+
+```rust
+pub trait CgroupManager {
+    fn add_task(&self, pid: Pid) -> Result<()>;
+    fn apply(&self, controller_opt: &ControllerOpt) -> Result<()>;
+    fn remove(&self) -> Result<()>;
+    fn freeze(&self, state: FreezerState) -> Result<()>;
+    fn stats(&self) -> Result<Stats>;
+    fn get_all_pids(&self) -> Result<Vec<Pid>>;
+}
+```
+
+The determination is made by `get_cgroup_setup()` function.
+
+```rust 
+/// Determines the cgroup setup of the system. Systems typically have one of
+/// three setups:
+/// - Unified: Pure cgroup v2 system.
+/// - Legacy: Pure cgroup v1 system.
+/// - Hybrid: Hybrid is basically a cgroup v1 system, except for
+///   an additional unified hierarchy which doesn't have any
+///   controllers attached. Resource control can purely be achieved
+///   through the cgroup v1 hierarchy, not through the cgroup v2 hierarchy.
+pub fn get_cgroup_setup() -> Result<CgroupSetup>
+```
+### Running Examples
+
+There are example files in the `libcgroup/examples/*.rs` pattern.
+
+The nightly cargo build is required to run the examples.
+
+Run the examples below as follows:
+
+```bash 
+rustup install nightly # Install nightly cargo
+cargo +nightly run --example examples/bpf    # Run BPF example
+cargo +nightly run --example examples/create # Run create example 
+```

crates/libcgroups/examples/create.rs

@@ -0,0 +1,22 @@
+use anyhow::Result;
+use libcgroups::common::{create_cgroup_manager, DEFAULT_CGROUP_ROOT};
+use nix::libc::pid_t;
+use nix::unistd::Pid;
+use std::path::Path;
+use std::process::Command;
+
+fn main() -> Result<()> {
+    // Create cgroup manager
+    let manager = create_cgroup_manager(Path::new(DEFAULT_CGROUP_ROOT), false, "example-cgroup")?;
+
+    // Run process
+    let cmd = Command::new("sh")
+        .args(["-c", "sleep 100"])
+        .spawn()
+        .expect("spawning sleep");
+
+    // Add the new process to the cgroup
+    manager.add_task(Pid::from_raw(cmd.id() as pid_t))?;
+
+    Ok(())
+}

crates/libcgroups/src/common.rs

@@ -29,6 +29,29 @@ use super::stats::Stats;
 pub const CGROUP_PROCS: &str = "cgroup.procs";
 pub const DEFAULT_CGROUP_ROOT: &str = "/sys/fs/cgroup";
 
+/// Create a cgroup with cgroup manager
+///
+/// # Example
+///
+/// ```no_run
+///    use libcgroups::common::{create_cgroup_manager, DEFAULT_CGROUP_ROOT};
+///    use nix::libc::pid_t;
+///    use nix::unistd::Pid;
+///    use std::path::Path;
+///    use std::process::Command;
+///    
+///    // Create cgroup manager
+///    let manager = create_cgroup_manager(Path::new(DEFAULT_CGROUP_ROOT), false, "example-cgroup")?;
+///
+///    // Run process
+///    let cmd = Command::new("sh")
+///        .args(["-c", "sleep 100"])
+///        .spawn()
+///        .expect("spawning sleep");
+///
+///    // Add the new process to the cgroup
+///    manager.add_task(Pid::from_raw(cmd.id() as pid_t))?;
+/// ```
 pub trait CgroupManager {
     /// Adds a task specified by its pid to the cgroup
     fn add_task(&self, pid: Pid) -> Result<()>;