manager: Introduce SystemdManager

Systemd manager takes cgroups path in the format of
"parent:scope_prefix:name" to create and manipulate cgroups through
systemd. It does value conversions for resources defined in the Linux
resources from the OCI spec, such as CPU quota, period, etc.

Signed-off-by: Xuewei Niu <[email protected]>

Author: justxuewei

src/manager/error.rs

@@ -4,6 +4,7 @@
 //
 
 use crate::fs::error::Error as CgroupfsError;
+use crate::systemd::error::Error as SystemdError;
 
 pub type Result<T> = std::result::Result<T, Error>;
 
@@ -17,4 +18,7 @@ pub enum Error {
 
     #[error("cgroupfs error: {0}")]
     Cgroupfs(#[from] CgroupfsError),
+
+    #[error("systemd error: {0}")]
+    Systemd(#[from] SystemdError),
 }

src/manager/mod.rs

@@ -7,6 +7,8 @@ mod error;
 pub use error::{Error, Result};
 mod fs;
 pub use fs::FsManager;
+mod systemd;
+pub use systemd::SystemdManager;
 mod conv;
 
 use oci_spec::runtime::LinuxResources;

src/manager/systemd.rs

@@ -0,0 +1,333 @@
+// Copyright (c) 2025 Ant Group
+//
+// SPDX-License-Identifier: Apache-2.0 or MIT
+//
+
+use std::collections::HashMap;
+
+use oci_spec::runtime::{LinuxCpu, LinuxMemory, LinuxPids, LinuxResources};
+
+use crate::manager::conv;
+use crate::manager::error::{Error, Result};
+use crate::manager::fs::{join_path, FsManager};
+use crate::systemd::{
+    cpu, cpuset, memory, pids, Property, SystemdCgroup, DEFAULT_SLICE, SCOPE_SUFFIX, SLICE_SUFFIX,
+};
+use crate::{CgroupPid, FreezerState, Manager, Stats};
+
+/// Default kernel value for cpu quota period is 100000 us (100 ms), same
+/// for v1 [1] and v2 [2].
+///
+/// 1: https://www.kernel.org/doc/html/latest/scheduler/sched-bwc.html
+/// 2: https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html
+const DEFAULT_CPU_QUOTA_PERIOD: u64 = 100_000; // 100ms
+
+pub struct SystemdManager {
+    /// The name of slice
+    slice: String,
+    /// The name of unit
+    unit: String,
+    /// Systemd cgroup
+    cgroup: SystemdCgroup,
+    /// Cgroupfs manager
+    fs_manager: FsManager,
+}
+
+impl SystemdManager {
+    /// Create a new `SystemdManager` from a cgroup path.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - A string slice that holds the cgroup path in the format
+    ///   "parent:scope_prefix:name".
+    pub fn new(path: &str) -> Result<Self> {
+        let parts: Vec<&str> = path.split(':').collect();
+        if parts.len() != 3 {
+            return Err(Error::InvalidArgument);
+        }
+
+        let slice = if parts[0].is_empty() {
+            DEFAULT_SLICE.to_string()
+        } else {
+            parts[0].to_string()
+        };
+
+        let slice_base = expand_slice(&slice)?;
+        let unit = new_unit_name(parts[1], parts[2]);
+
+        let fs_base = join_path(&slice_base, &unit);
+        let fs_manager = FsManager::load(&fs_base)?;
+
+        let cgroup = SystemdCgroup::new(&slice, &unit)?;
+
+        Ok(Self {
+            slice,
+            unit,
+            fs_manager,
+            cgroup,
+        })
+    }
+}
+
+impl SystemdManager {
+    /// Get the slice name.
+    pub fn slice(&self) -> &str {
+        &self.slice
+    }
+
+    /// Get the unit name.
+    pub fn unit(&self) -> &str {
+        &self.unit
+    }
+
+    /// Get the cgroup path, see `FsManager::paths()`.
+    pub fn paths(&self) -> &HashMap<String, String> {
+        self.fs_manager.paths()
+    }
+
+    /// Get the cgroup mountpoints, see `FsManager::mounts()`.
+    pub fn mounts(&self) -> &HashMap<String, String> {
+        self.fs_manager.mounts()
+    }
+
+    fn set_cpuset(
+        &self,
+        props: &mut Vec<Property>,
+        linux_cpu: &LinuxCpu,
+        systemd_version: usize,
+    ) -> Result<()> {
+        if let Some(cpus) = linux_cpu.cpus().as_ref() {
+            let (id, value) = cpuset::cpuset_cpus(cpus, systemd_version)?;
+            props.push((id, value.into()));
+        }
+
+        if let Some(mems) = linux_cpu.mems().as_ref() {
+            let (id, value) = cpuset::cpuset_mems(mems, systemd_version)?;
+            props.push((id, value.into()));
+        }
+
+        Ok(())
+    }
+
+    fn set_cpu(
+        &self,
+        props: &mut Vec<Property>,
+        linux_cpu: &LinuxCpu,
+        systemd_version: usize,
+    ) -> Result<()> {
+        if let Some(shares) = linux_cpu.shares() {
+            let shares = if self.v2() {
+                conv::cpu_shares_to_cgroup_v2(shares)
+            } else {
+                shares
+            };
+            let (id, value) = cpu::shares(shares, self.v2())?;
+            props.push((id, value.into()));
+        }
+
+        let period = linux_cpu.period().unwrap_or(0);
+        let quota = linux_cpu.quota().unwrap_or(0);
+
+        if period != 0 {
+            let (id, value) = cpu::period(period, systemd_version)?;
+            props.push((id, value.into()));
+        }
+
+        if period != 0 || quota != 0 {
+            // Corresponds to USEC_INFINITY in systemd
+            let mut cpu_quota_per_sec_usec = u64::MAX;
+            let mut period = period;
+            if quota > 0 {
+                if period == 0 {
+                    period = DEFAULT_CPU_QUOTA_PERIOD;
+                }
+                // systemd converts CPUQuotaPerSecUSec (microseconds per
+                // CPU second) to CPUQuota (integer percentage of CPU)
+                // internally. This means that if a fractional percent of
+                // CPU is indicated by Resources.CpuQuota, we need to round
+                // up to the nearest 10ms (1% of a second) such that child
+                // cgroups can set the cpu.cfs_quota_us they expect.
+                cpu_quota_per_sec_usec = ((quota as u64) * 1_000_000) / period;
+                if cpu_quota_per_sec_usec % 10_000 != 0 {
+                    cpu_quota_per_sec_usec = (cpu_quota_per_sec_usec / 10_000 + 1) * 10_000;
+                }
+            }
+            let (id, value) = cpu::quota(cpu_quota_per_sec_usec)?;
+            props.push((id, value.into()));
+        }
+
+        Ok(())
+    }
+
+    fn set_memory(&self, props: &mut Vec<Property>, linux_memory: &LinuxMemory) -> Result<()> {
+        let v2 = self.v2();
+
+        let mem_limit = linux_memory.limit().unwrap_or(0);
+        if mem_limit != 0 {
+            let (id, value) = memory::limit(mem_limit, v2)?;
+            props.push((id, value.into()));
+        }
+
+        let reservation = linux_memory.reservation().unwrap_or(0);
+        if reservation != 0 && v2 {
+            let (id, value) = memory::low(reservation, v2)?;
+            props.push((id, value.into()));
+        }
+
+        let memswap_limit = linux_memory.swap().unwrap_or(0);
+        if memswap_limit != 0 && v2 {
+            let memswap_limit = conv::memory_swap_to_cgroup_v2(memswap_limit, mem_limit)?;
+            let (id, value) = memory::swap(memswap_limit, v2)?;
+            props.push((id, value.into()));
+        }
+
+        Ok(())
+    }
+
+    fn set_pids(&self, props: &mut Vec<Property>, linux_pids: &LinuxPids) -> Result<()> {
+        let limit = linux_pids.limit();
+        if limit == -1 || limit > 0 {
+            let (id, value) = pids::max(limit)?;
+            props.push((id, value.into()));
+        }
+
+        Ok(())
+    }
+}
+
+impl Manager for SystemdManager {
+    fn apply(&self, pid: CgroupPid) -> Result<()> {
+        if self.cgroup.exists()? {
+            let subcgroup = self.fs_manager.subcgroup();
+            self.cgroup.add_process(pid, subcgroup)?;
+
+            return Ok(());
+        }
+
+        self.cgroup.start(pid)?;
+        // The fs_manager was created in load mode, which doesn't create
+        // the cgroups. So we create them here.
+        self.fs_manager.cgroup.create()?;
+
+        Ok(())
+    }
+
+    fn cgroup_path(&self, subsystem: Option<&str>) -> Result<String> {
+        self.fs_manager.cgroup_path(subsystem)
+    }
+
+    fn destroy(&mut self) -> Result<()> {
+        self.cgroup.kill()?;
+        self.fs_manager.destroy()?;
+
+        Ok(())
+    }
+
+    fn enable_cpus_topdown(&self, cpus: &str) -> Result<()> {
+        self.fs_manager.enable_cpus_topdown(cpus)
+    }
+
+    fn freeze(&self, state: FreezerState) -> Result<()> {
+        match state {
+            FreezerState::Thawed => self.cgroup.thaw()?,
+            FreezerState::Frozen => self.cgroup.freeze()?,
+            FreezerState::Freezing => return Err(Error::InvalidArgument),
+        }
+
+        Ok(())
+    }
+
+    fn pids(&self) -> Result<Vec<CgroupPid>> {
+        self.fs_manager.pids()
+    }
+
+    fn set(&self, resources: &LinuxResources) -> Result<()> {
+        let mut props = vec![];
+
+        let systemd_version = self.cgroup.systemd_version()?;
+
+        if let Some(linux_cpu) = resources.cpu() {
+            self.set_cpuset(&mut props, linux_cpu, systemd_version)?;
+            self.set_cpu(&mut props, linux_cpu, systemd_version)?;
+        }
+
+        if let Some(linux_memory) = resources.memory() {
+            self.set_memory(&mut props, linux_memory)?;
+        }
+
+        if let Some(linux_pids) = resources.pids() {
+            self.set_pids(&mut props, linux_pids)?;
+        }
+
+        Ok(())
+    }
+
+    fn stats(&self) -> Result<Stats> {
+        self.fs_manager.stats()
+    }
+
+    fn systemd(&self) -> bool {
+        true
+    }
+
+    fn v2(&self) -> bool {
+        self.fs_manager.v2()
+    }
+}
+
+/// Expand a slice name to a full path in the filesystem.
+///
+/// # Arguments
+///
+/// * `slice` - A string slice that holds the slice name in the format
+///   "xxx-yyy-zzz.slice".
+///
+/// # Returns
+///
+/// A string that represents the full path of the slice in the filesystem.
+/// In the above case, the value would be "xxx/xxx-yyy/xxx-yyy-zzz.slice".
+fn expand_slice(slice: &str) -> Result<String> {
+    // Name has to end with ".slice", but can't be just ".slice".
+    if !slice.ends_with(SLICE_SUFFIX) || slice.len() < SLICE_SUFFIX.len() {
+        return Err(Error::InvalidArgument);
+    }
+
+    // Path-separators are not allowed.
+    if slice.contains('/') {
+        return Err(Error::InvalidArgument);
+    }
+
+    let name = slice.trim_end_matches(SLICE_SUFFIX);
+
+    // If input was -.slice, we should just return root now
+    if name == "-" {
+        return Ok("".to_string());
+    }
+
+    let mut slice_path = String::new();
+    let mut prefix = String::new();
+    for sub_slice in name.split('-') {
+        if sub_slice.is_empty() {
+            return Err(Error::InvalidArgument);
+        }
+
+        slice_path = format!("{}/{}{}{}", slice_path, prefix, sub_slice, SLICE_SUFFIX);
+        prefix = format!("{}{}-", prefix, sub_slice);
+    }
+
+    // We need a relative path, so remove the first slash.
+    slice_path.remove(0);
+
+    Ok(slice_path)
+}
+
+fn new_unit_name(scope_prefix: &str, name: &str) -> String {
+    // By default, we create a scope unless the user explicitly asks
+    // for a slice.
+    if !name.ends_with(SLICE_SUFFIX) {
+        // {scope_prefix}-{name}.scope
+        return format!("{}-{}{}", scope_prefix, name, SCOPE_SUFFIX);
+    }
+
+    name.to_string()
+}