0
# Node Operations
1

2
Node classes for representing cgroup filesystem objects with creation, deletion, and traversal capabilities. Provides hierarchical representation of cgroups with controller integration and specialized functionality for different node types.
3

4
## Capabilities
5

6
### Basic Node Management
7

8
Core node class representing individual cgroup directories with filesystem operations and controller integration.
9

10
```python { .api }
11
class Node:
12
    """Basic cgroup tree node with filesystem operations."""
13
    
14
    # Node type constants
15
    NODE_ROOT: bytes
16
    NODE_CONTROLLER_ROOT: bytes  
17
    NODE_SLICE: bytes
18
    NODE_SCOPE: bytes
19
    NODE_CGROUP: bytes
20
    
21
    # Controller mapping
22
    CONTROLLERS: dict  # Maps controller names to controller classes
23
    
24
    def __init__(self, name, parent=None):
25
        """
26
        Create a node representing a cgroup directory.
27
        
28
        Parameters:
29
        - name: str or bytes, node name/directory name
30
        - parent: Node, parent node (None for root)
31
        """
32
    
33
    @property
34
    def full_path(self) -> bytes:
35
        """Absolute system path to the node directory."""
36
    
37
    @property 
38
    def path(self) -> bytes:
39
        """Node's relative path from the root node."""
40
    
41
    @property
42
    def node_type(self) -> bytes:
43
        """Type of node (root, controller_root, slice, scope, cgroup)."""
44
    
45
    @property
46
    def controller_type(self) -> bytes:
47
        """Controller type for this node (cpu, memory, etc.)."""
48
    
49
    @property
50
    def controller(self):
51
        """Controller instance for managing this node's properties."""
52
    
53
    def create_cgroup(self, name):
54
        """
55
        Create a cgroup directory and attach it as child node.
56
        
57
        Parameters:
58
        - name: str or bytes, cgroup name
59
        
60
        Returns:
61
        Node object for the created cgroup
62
        
63
        Raises:
64
        RuntimeError if cgroup already exists
65
        OSError if filesystem operation fails
66
        """
67
    
68
    def delete_cgroup(self, name):
69
        """
70
        Delete a cgroup directory and detach from children.
71
        
72
        Parameters:
73
        - name: str or bytes, cgroup name
74
        
75
        Raises:
76
        OSError if cgroup is not empty or operation fails
77
        """
78
    
79
    def delete_empty_children(self):
80
        """
81
        Recursively delete all empty child cgroups.
82
        
83
        Walks through children and removes any empty directories.
84
        Continues recursively until no more empty children found.
85
        """
86
    
87
    def walk(self):
88
        """
89
        Walk through this node and its children - pre-order depth-first.
90
        
91
        Yields:
92
        Node objects in traversal order
93
        """
94
    
95
    def walk_up(self):
96
        """
97
        Walk through this node and its children - post-order depth-first.
98
        
99
        Yields:  
100
        Node objects in reverse traversal order
101
        """
102
```
103

104
Usage example:
105

106
```python
107
from cgroupspy.trees import Tree
108

109
# Create tree and get cpuset controller
110
t = Tree()
111
cpuset = t.get_node_by_path('/cpuset/')
112

113
# Create new cgroup
114
test_cgroup = cpuset.create_cgroup('test')
115
print(test_cgroup.full_path)  # b'/sys/fs/cgroup/cpuset/test'
116
print(test_cgroup.path)       # b'/cpuset/test'
117

118
# Configure the cgroup
119
test_cgroup.controller.cpus = {0, 1}
120
test_cgroup.controller.mems = {0}
121

122
# Create nested cgroup
123
nested = test_cgroup.create_cgroup('nested')
124

125
# Clean up empty cgroups
126
cpuset.delete_empty_children()
127

128
# Delete specific cgroup
129
cpuset.delete_cgroup('test')
130
```
131

132
### Grouped Control Nodes
133

134
Node class for grouping multiple nodes by hierarchy position, enabling unified access to same-named cgroups across different controllers.
135

136
```python { .api }
137
class NodeControlGroup:
138
    """Groups multiple nodes by their position in cgroup hierarchy."""
139
    
140
    def __init__(self, name, parent=None):
141
        """
142
        Create a control group node.
143
        
144
        Parameters:
145
        - name: str or bytes, group name
146
        - parent: NodeControlGroup, parent group (None for root)
147
        """
148
    
149
    @property
150
    def name(self) -> bytes:
151
        """Control group name."""
152
    
153
    @property
154
    def path(self) -> bytes:
155
        """Control group path with extension handling."""
156
    
157
    @property
158
    def children(self) -> list:
159
        """List of child control groups."""
160
    
161
    @property
162
    def controllers(self) -> dict:
163
        """Dictionary of controllers by type."""
164
    
165
    @property
166
    def nodes(self) -> list:
167
        """List of underlying Node objects."""
168
    
169
    @property
170
    def group_tasks(self) -> set:
171
        """All process IDs in the hierarchy affected by this group."""
172
    
173
    @property
174
    def tasks(self) -> set:
175
        """Process IDs in this exact group only."""
176
    
177
    def add_node(self, node):
178
        """
179
        Add a Node object to the control group.
180
        
181
        Parameters:
182
        - node: Node, node to add (one per controller type)
183
        
184
        Raises:
185
        RuntimeError if controller type already assigned
186
        """
187
```
188

189
Usage example:
190

191
```python
192
from cgroupspy.trees import GroupedTree
193

194
# Create grouped tree
195
gt = GroupedTree()
196

197
# Find a control group
198
machine = gt.get_node_by_name('machine')
199

200
# Access controllers through the group
201
print(machine.cpu.shares)        # CPU controller
202
print(machine.memory.limit_in_bytes)  # Memory controller
203

204
# View all tasks in the group hierarchy
205
print(machine.group_tasks)       # All PIDs in hierarchy
206
print(machine.tasks)             # PIDs in this exact group
207

208
# Access child groups
209
for child in machine.children:
210
    print(f"Child: {child.name}")
211
```
212

213
### Virtual Machine Nodes
214

215
Specialized control group node for QEMU virtual machine management with VM-specific properties and component access.
216

217
```python { .api }
218
class NodeVM(NodeControlGroup):
219
    """Specialized control group for QEMU virtual machine nodes."""
220
    
221
    @property
222
    def verbose_name(self) -> str:
223
        """Human-readable VM name or 'AnonymousVM' if unavailable."""
224
    
225
    @property
226
    def emulator(self):
227
        """NodeControlGroup for the emulator process or None."""
228
    
229
    @property  
230
    def vcpus(self) -> list:
231
        """List of NodeControlGroup objects for individual VCPUs."""
232
```
233

234
Usage example:
235

236
```python
237
from cgroupspy.trees import VMTree
238

239
# Create VM tree
240
vmt = VMTree()
241

242
# Get VM node
243
vm = vmt.get_vm_node("test-vm-uuid")
244

245
# VM information
246
print(vm.verbose_name)           # VM display name
247
print(vm.path)                   # VM cgroup path
248

249
# VM resource limits
250
print(vm.cpu.shares)             # CPU shares
251
print(vm.memory.limit_in_bytes)  # Memory limit
252
print(vm.cpuset.cpus)            # CPU pinning
253

254
# VM components
255
emulator = vm.emulator
256
if emulator:
257
    print(emulator.cpu.shares)   # Emulator CPU shares
258

259
# VCPU management
260
vcpus = vm.vcpus
261
for i, vcpu in enumerate(vcpus):
262
    print(f"VCPU {i} CPUs: {vcpu.cpuset.cpus}")
263
    
264
    # Pin VCPU to specific cores
265
    vcpu.cpuset.cpus = {i % 4}   # Pin to core based on VCPU index
266

267
# Task management
268
print(vm.tasks)                  # PIDs directly in VM cgroup
269
print(vm.group_tasks)            # All PIDs in VM hierarchy
270
```