libcgroup and libcontainers examples and README

crates/libcgroups/Cargo.toml

@@ -29,7 +29,7 @@ dbus = { version = "0.9.7", optional = true }
 fixedbitset = "0.4.2"
 serde = { version = "1.0", features = ["derive"] }
 rbpf = {version = "0.1.0", optional = true }
-libbpf-sys = { version = "1.1.1+v1.0.1", optional = true }
+libbpf-sys = { version = "1.1.1", optional = true }
 errno = { version = "0.2.8", optional = true }
 libc = { version = "0.2.139", optional = true }
 
@@ -42,3 +42,12 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 env_logger = "0.10"
 serial_test = "1.0.0"
+
+# TODO https://github.com/containers/youki/issues/1499
+#[[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<()>;

crates/libcontainer/Cargo.toml

@@ -12,7 +12,8 @@ rust-version = "1.58.1"
 keywords = ["youki", "container", "cgroups"]
 
 [features]
-default = ["systemd", "v2", "v1"]
+default = ["systemd", "v2", "v1", "libseccomp"]
+libseccomp = ["dep:libseccomp"]
 wasm-wasmer = ["wasmer", "wasmer-wasi"]
 wasm-wasmedge = ["wasmedge-sdk/standalone"]
 wasm-wasmtime = ["wasmtime", "wasmtime-wasi"]
@@ -21,6 +22,7 @@ v2 = ["libcgroups/v2"]
 v1 = ["libcgroups/v1"]
 cgroupsv2_devices = ["libcgroups/cgroupsv2_devices"]
 
+
 [dependencies]
 anyhow = "1.0"
 bitflags = "1.3.2"
@@ -38,7 +40,7 @@ path-clean = "0.1.0"
 procfs = "0.14.2"
 prctl = "1.0.0"
 libcgroups = { version = "0.0.4", path = "../libcgroups", default-features = false }
-libseccomp = { version = "0.3.0" }
+libseccomp = { version = "0.3.0", optional=true }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 syscalls = "0.6.7"