# libcgroups

libcgroups is the crate that contains functionality to work with Linux cgroups. This provide an easy to use interface over reading and writing cgroups files, as well as various structs that represent the cgroups data.

The modules that it exposes are :

- common
- stats
- systemd
- test_manager
- v1
- v2

Following is a short explanation of these modules.

### common

This module contains functionality that is general to any type of cgroup. Some of the things it provides are:

- trait `CgroupManager` which gives and interface for the following:

  - add a task to a cgroup
  - apply resource restriction
  - remove a cgroup
  - control freezer cgroup state
  - get stats from a cgroup
  - get pids belonging to the cgroup

- functions `write_cgroup_file_str` and `write_cgroup_file` which write data to a cgroup file
- function `read_cgroup_file` which reads data from given cgroup file
- function `get_cgroup_setup` which returns setup of cgroups (v1,v2, hybrid) on the system

### stats

This module has functionalities related to statistics data of the cgroups, and struts representing it.

Some of the things it exposes are

- struct `Stats` which contains following structs:

  - `CpuStats` : contains cpu usage and throttling information

  - `MemoryStats` : contains usage of memory, swap and memory combined, kernel memory, kernel tcp memory and other memory stats

  - `PidStats` : contains current number of active pids and allowed number of pids

  - `BlkioStats` : contains block io related stats, such as number of bytes transferred from/to a device in cgroup, number of io operations done by a device in cgroup, device access and queue information etc.

  - `HugeTlbStats` : containing stats for Huge TLB such as usage, max_usage, and fail count

- function `supported_page_size` which returns hugepage size supported by the system

- utility functions to operate with data in cgroups files such as:

  - `parse_single_value` : reads file expecting it to have a single value, and returns the value

  - `parse_flat_keyed_data` : parses cgroup file data which is in flat keyed format (key value)

  - `parse_nested_keyed_data` : parses cgroup file data which is in nested keyed format (key list of values)

  - `parse_device_number` : parses major and minor number of device

### systemd

This is the module used by youki to interact with systemd, and it exposes several functions to interact:

- function `booted` to check if the system was booted with systemd or not

- module `controller_type`, which contains enum `ControllerType` which is used to specify cgroup controllers available on a system

- module `manager`, which contains `Manager` struct, which is the cgroup manager, and contain information such as the root cgroups path, path for the specific cgroups, client to communicate with systemd etc. This also implements `CgroupManager` trait, and thus can be used for cgroups related operations.

### test_manager

This exposes a `TestManager` struct which can be used as dummy for cgroup testing purposes, which also implements `CgroupManager`.

### v1 and v2

These two modules contains functionalities specific to cgroups version 1 and version 2. Both of these expose respective cgroup managers, which can be used to manage that type of cgroup, as well as some utility functions related to respective cgroup version, such as `get_mount_points` (for v1 and v2), `get_subsystem_mount points` (for v1), and `get_available_controllers` (for v2) etc.

The v2 module also exposes devices module, which provides functionality for working with bpf, such as load a bpf program, query info of a bpf program, attach and detach a bpf program to a cgroup, etc.
