0
# Tree Management
1
2
Tree structures for representing and navigating cgroup hierarchies. cgroupspy provides three main tree representations optimized for different use cases: basic filesystem representation, grouped controller management, and virtual machine operations.
3
4
## Capabilities
5
6
### Basic Tree Operations
7
8
Direct filesystem representation of the cgroups hierarchy, providing one-to-one mapping with the underlying filesystem structure.
9
10
```python { .api }
11
class BaseTree:
12
"""Basic cgroup node tree representing filesystem structure."""
13
14
def __init__(self, root_path="/sys/fs/cgroup/", groups=None, sub_groups=None):
15
"""
16
Construct a basic cgroup node tree.
17
18
Parameters:
19
- root_path: str, path to cgroups root (default: "/sys/fs/cgroup/")
20
- groups: list, specific controllers to include (default: all available)
21
- sub_groups: list, specific slices to include (creates if missing)
22
"""
23
24
@property
25
def groups(self) -> list:
26
"""List of controller groups in the tree."""
27
28
@property
29
def sub_groups(self) -> list:
30
"""List of sub-groups/slices in the tree."""
31
32
def walk(self, root=None):
33
"""
34
Walk through each node - pre-order depth-first.
35
36
Parameters:
37
- root: Node, starting node (default: tree root)
38
39
Yields:
40
Node objects in traversal order
41
"""
42
43
def walk_up(self, root=None):
44
"""
45
Walk through each node - post-order depth-first.
46
47
Parameters:
48
- root: Node, starting node (default: tree root)
49
50
Yields:
51
Node objects in reverse traversal order
52
"""
53
```
54
55
### Path-Based Tree Access
56
57
Extended tree with path-based node lookup capabilities, enabling direct access to nodes by their filesystem paths.
58
59
```python { .api }
60
class Tree(BaseTree):
61
"""Tree with path-based node lookup."""
62
63
def get_node_by_path(self, path):
64
"""
65
Find node by relative path from root.
66
67
Parameters:
68
- path: str or bytes, relative path (e.g., "/cpuset/test")
69
70
Returns:
71
Node object or None if not found
72
"""
73
```
74
75
Usage example:
76
77
```python
78
from cgroupspy.trees import Tree
79
80
# Create tree
81
t = Tree()
82
83
# Access specific controller
84
cpuset = t.get_node_by_path('/cpuset/')
85
memory = t.get_node_by_path('/memory/')
86
87
# Access nested cgroups
88
test_group = t.get_node_by_path('/cpuset/isolated.scope/')
89
```
90
91
### Grouped Tree Management
92
93
Tree providing unified access to cgroup partitions with the same name across different controllers. Allows accessing related controllers through a single interface.
94
95
```python { .api }
96
class GroupedTree:
97
"""Tree with grouped access to same-named partitions across controllers."""
98
99
def __init__(self, root_path="/sys/fs/cgroup", groups=None, sub_groups=None):
100
"""
101
Construct a grouped tree.
102
103
Parameters:
104
- root_path: str, path to cgroups root (default: "/sys/fs/cgroup")
105
- groups: list, specific controllers to include
106
- sub_groups: list, specific slices to include
107
"""
108
109
def walk(self, root=None):
110
"""
111
Walk the control tree - pre-order depth-first.
112
113
Parameters:
114
- root: NodeControlGroup, starting node (default: control root)
115
116
Yields:
117
NodeControlGroup objects in traversal order
118
"""
119
120
def walk_up(self, root=None):
121
"""
122
Walk the control tree - post-order depth-first.
123
124
Parameters:
125
- root: NodeControlGroup, starting node (default: control root)
126
127
Yields:
128
NodeControlGroup objects in reverse traversal order
129
"""
130
131
def get_node_by_name(self, pattern):
132
"""
133
Find control group by name pattern.
134
135
Parameters:
136
- pattern: str or bytes, name pattern to match
137
138
Returns:
139
NodeControlGroup or None if not found
140
"""
141
142
def get_node_by_path(self, path):
143
"""
144
Find control group by exact path.
145
146
Parameters:
147
- path: str or bytes, exact path to match
148
149
Returns:
150
NodeControlGroup or None if not found
151
"""
152
```
153
154
Usage example:
155
156
```python
157
from cgroupspy.trees import GroupedTree
158
159
# Create grouped tree
160
gt = GroupedTree()
161
162
# Access a partition across all controllers
163
machine_group = gt.get_node_by_name('machine')
164
165
# Access individual controllers for the group
166
print(machine_group.cpu.shares) # CPU controller
167
print(machine_group.memory.limit_in_bytes) # Memory controller
168
print(machine_group.cpuset.cpus) # CPU set controller
169
```
170
171
### Virtual Machine Tree
172
173
Specialized tree for managing libvirt virtual machine cgroups with VM-specific utilities and automatic VM detection.
174
175
```python { .api }
176
class VMTree(GroupedTree):
177
"""Specialized tree for libvirt VM cgroup management."""
178
179
def __init__(self, *args, **kwargs):
180
"""
181
Construct VM tree with automatic VM detection.
182
183
Inherits GroupedTree parameters.
184
"""
185
186
@property
187
def vms(self) -> dict:
188
"""Dictionary of detected VM nodes keyed by VM name."""
189
190
def get_vm_node(self, name):
191
"""
192
Get VM node by name with various name formats.
193
194
Parameters:
195
- name: str, VM name (tries multiple formats)
196
197
Returns:
198
NodeVM object or None if not found
199
200
Name formats tried:
201
- exact name
202
- name.libvirt-qemu
203
- machine-qemu{name}
204
"""
205
```
206
207
Usage example:
208
209
```python
210
from cgroupspy.trees import VMTree
211
212
# Create VM tree
213
vmt = VMTree()
214
215
# List all VMs
216
print(vmt.vms)
217
218
# Get specific VM
219
vm = vmt.get_vm_node("1ce10f47-fb4e-4b6a-8ee6-ba34940cdda7")
220
221
# Access VM resources
222
print(vm.cpu.shares) # VM CPU shares
223
print(vm.memory.limit_in_bytes) # VM memory limit
224
print(vm.cpuset.cpus) # VM CPU pinning
225
226
# Access VM components
227
print(vm.emulator) # Emulator process cgroup
228
print(vm.vcpus) # List of VCPU cgroups
229
230
# Modify VCPU pinning
231
vcpu1 = vm.children[0]
232
vcpu1.cpuset.cpus = {1, 2, 3}
233
```