0
# cgroupspy
1

2
A Python library for managing Linux control groups (cgroups) with a pythonic interface to the cgroups filesystem. It provides object representations and utilities for reading/writing cgroup configuration files, managing resource limits, and controlling process groups. The library supports multiple tree representations including basic filesystem trees, grouped trees for managing partitions across controllers, and specialized virtual machine utilities.
3

4
## Package Information
5

6
- **Package Name**: cgroupspy
7
- **Language**: Python
8
- **Installation**: `pip install cgroupspy`
9
- **Python Support**: 2.7, 3.6+
10

11
## Core Imports
12

13
```python
14
import cgroupspy
15
from cgroupspy import trees
16
```
17

18
Common for working with cgroup trees:
19

20
```python
21
from cgroupspy.trees import Tree, GroupedTree, VMTree
22
```
23

24
For working with controllers and content types:
25

26
```python
27
from cgroupspy.controllers import Controller, CpuController, MemoryController
28
from cgroupspy.contenttypes import DeviceAccess, DeviceThrottle
29
from cgroupspy.utils import walk_tree, walk_up_tree, split_path_components
30
```
31

32
## Basic Usage
33

34
```python
35
from cgroupspy import trees
36

37
# Create a basic cgroup tree representation
38
t = trees.Tree()
39

40
# Access the root node
41
print(t.root)  # <Node />
42
print(t.root.children)  # List of controller nodes
43

44
# Get a specific controller
45
cpuset = t.get_node_by_path('/cpuset/')
46
print(cpuset.controller)  # CpuSetController instance
47

48
# Read current CPU restrictions
49
print(cpuset.controller.cpus)  # set([0, 1])
50

51
# Create a new cgroup
52
test_cgroup = cpuset.create_cgroup('test')
53
print(test_cgroup)  # <Node /cpuset/test>
54

55
# Modify CPU restrictions
56
test_cgroup.controller.cpus = [1]
57
print(test_cgroup.controller.cpus)  # set([1])
58

59
# Manage process tasks
60
test_cgroup.controller.tasks = [1234, 5678]  # Assign PIDs to cgroup
61
```
62

63
## Architecture
64

65
cgroupspy provides three main tree representations for different use cases:
66

67
- **BaseTree/Tree**: Direct filesystem representation of cgroups hierarchy
68
- **GroupedTree**: Grouped access to partitions across different controllers (cpu, memory, etc.)
69
- **VMTree**: Specialized tree for libvirt virtual machine management
70

71
The controller system provides typed interfaces to cgroup files through descriptor-based property access, automatically handling data conversion between Python objects and cgroup-compatible strings.
72

73
## Capabilities
74

75
### Tree Representations
76

77
Core tree structures for representing and navigating cgroup hierarchies. Includes basic filesystem trees, grouped trees for cross-controller management, and specialized VM trees.
78

79
```python { .api }
80
class Tree:
81
    def __init__(self, root_path="/sys/fs/cgroup/", groups=None, sub_groups=None): ...
82
    def get_node_by_path(self, path): ...
83

84
class GroupedTree:
85
    def __init__(self, root_path="/sys/fs/cgroup", groups=None, sub_groups=None): ...
86
    def get_node_by_name(self, pattern): ...
87
    def get_node_by_path(self, path): ...
88

89
class VMTree(GroupedTree):
90
    def get_vm_node(self, name): ...
91
```
92

93
[Tree Management](./tree-management.md)
94

95
### Node Operations
96

97
Node classes for representing cgroup filesystem objects with creation, deletion, and traversal capabilities. Supports basic nodes, grouped control nodes, and specialized VM nodes.
98

99
```python { .api }
100
class Node:
101
    def __init__(self, name, parent=None): ...
102
    def create_cgroup(self, name): ...
103
    def delete_cgroup(self, name): ...
104
    def walk(self): ...
105

106
class NodeControlGroup:
107
    def __init__(self, name, parent=None): ...
108
    def add_node(self, node): ...
109

110
class NodeVM(NodeControlGroup):
111
    @property
112
    def emulator(self): ...
113
    @property
114
    def vcpus(self): ...
115
```
116

117
[Node Operations](./node-operations.md)
118

119
### Resource Controllers
120

121
Controller classes providing typed access to cgroup resource management files. Includes CPU, memory, device, network, and block I/O controllers with automatic data conversion.
122

123
```python { .api }
124
class CpuController(Controller):
125
    cfs_period_us: int
126
    cfs_quota_us: int
127
    shares: int
128

129
class MemoryController(Controller):
130
    limit_in_bytes: int
131
    usage_in_bytes: int
132
    max_usage_in_bytes: int
133

134
class CpuSetController(Controller):
135
    cpus: set
136
    mems: set
137
```
138

139
[Resource Controllers](./resource-controllers.md)
140

141
### Utilities
142

143
Utility functions for tree traversal, path manipulation, and content type handling. Includes traversal algorithms and helper classes for cgroup file content conversion.
144

145
```python { .api }
146
def walk_tree(root):
147
    """Pre-order depth-first tree traversal."""
148

149
def walk_up_tree(root):
150
    """Post-order depth-first tree traversal."""
151

152
def split_path_components(path):
153
    """Split filesystem path into components."""
154
```
155

156
[Utilities](./utilities.md)
157

158
## Types
159

160
```python { .api }
161
class Controller:
162
    """Base controller for cgroup property access."""
163
    tasks: List[int]
164
    procs: List[int]
165
    
166
    def __init__(self, node): ...
167
    def get_property(self, filename: str) -> str: ...
168
    def set_property(self, filename: str, value) -> int: ...
169

170
class DeviceAccess:
171
    """Device access permissions configuration."""
172
    TYPE_ALL: str
173
    TYPE_CHAR: str 
174
    TYPE_BLOCK: str
175
    ACCESS_READ: int
176
    ACCESS_WRITE: int
177
    ACCESS_MKNOD: int
178
    
179
    def __init__(self, dev_type=None, major=None, minor=None, access=None): ...
180
    @property
181
    def can_read(self) -> bool: ...
182
    @property
183
    def can_write(self) -> bool: ...
184
    @property
185
    def can_mknod(self) -> bool: ...
186

187
class DeviceThrottle:
188
    """Device throttling configuration."""
189
    def __init__(self, limit, major=None, minor=None): ...
190
```