[PATCH 00/36] tuna: Add comprehensive cgroup v2 cpuset support

This patch series adds comprehensive support for cgroup v2 cpusets to tuna,
providing a modern, container-based approach to CPU and memory node isolation
alongside the existing affinity-based mechanisms.

Background
==========

Traditional CPU isolation in tuna works by modifying process affinity masks
system-wide. While effective, this approach has limitations for complex
workloads that benefit from explicit container-based organization. Cgroup v2
cpusets provide kernel-enforced isolation with NUMA-aware memory node
assignment, making them ideal for real-time and high-performance computing
workloads.

This implementation maintains full backward compatibility with existing tuna
functionality while adding new cpuset-based workflows for users who need
stronger isolation guarantees.

Key Features
============

Core Infrastructure (patches 7-11):
- Complete cpuset module (tuna/cpuset.py) with context manager support
- NUMA-aware automatic memory node detection and assignment
- Process blocklist protection to prevent system instability
- Comprehensive test suite (146 tests: 45 non-root + 101 root-required)

Cpuset Management Commands (patches 12-23):
- create: Create cpusets with auto-naming (tuna0, tuna1, etc.)
- list: List cpusets with filtering and verbosity options
- destroy: Clean up cpusets individually or by pattern
- move: Migrate processes to cpusets with thread/PID support
- show: Display detailed cpuset information
- status: System-wide cpuset overview with statistics
- modify: Runtime modification of CPUs, memory nodes, and isolation

Integration with Existing Commands (patches 24-35):
- isolate --cpuset: Create isolated and housekeeping cpusets with automatic
  process migration
- move --cpuset: Move threads/IRQs to cpusets instead of setting affinity
- run --cpuset: Launch processes directly in cpusets
- show_threads --cpuset: Filter display by cpuset membership
- show_threads -G: Enhanced cgroup display showing cpuset names

General Improvements (patches 1-6):
- Pattern matching warnings with opt-in -w/--warn flag
- Enhanced what_is command with updated kernel thread descriptions
- Comprehensive docstrings for converter functions
- Centralized input validation for CPU numbers and RT priorities

Documentation and Testing
=========================

- Complete API documentation in tuna/cpuset_README.md
- Updated man page (docs/tuna.8) with full cpuset command reference
- 146 comprehensive tests with clear root/non-root separation
- Test documentation in tests/README.md
- Usage examples for common cpuset workflows

Design Decisions
================

- Skip empty cpusets by default in list/status commands to reduce noise
- Auto-detect NUMA nodes from CPU assignments for optimal performance
- Process blocklist prevents moving critical system processes (systemd, etc.)
- Cpuset and affinity modes are mutually exclusive per command
- Context managers ensure cleanup even when operations fail

All changes follow existing tuna coding style and commit message conventions.
The implementation has been tested on both single-node and multi-NUMA systems.

John Kacur (36):
  tuna: Warn when user-specified patterns match zero threads or IRQs
  tuna: Suppress output when pattern matches zero results
  tuna: Make warnings opt-in with -w/--warn flag
  tuna: Enhance what_is command with new kernel thread descriptions and
    usability improvements
  tuna: Add comprehensive docstrings to converter functions
  tuna: Add centralized input validation for CPU numbers and RT
    priorities
  tuna: Add cpuset module for CPU isolation using cgroup v2
  tuna: Add comprehensive test suite for cpuset module
  tuna: Add CLI commands for cpuset management
  tuna: Add comprehensive test suite for cpuset CLI commands
  tuna: Add comprehensive test targets and documentation
  tuna: Add cpuset move command for process migration
  tuna: Add comprehensive tests for cpuset move command
  tuna: Add NUMA-aware memory node assignment for cpusets
  tuna: Add tests for NUMA-aware memory node assignment
  tuna: Add process blocklist to prevent shutdown issues
  tuna: Add memory nodes and blocklist warnings to cpuset list
  tuna: Add cpuset show and status commands
  tuna: Add tests for cpuset show and status commands
  tuna: Dynamically find free CPU for test_cpu_exclusive
  tuna: Change cpuset commands to skip empty by default
  tuna: Add cpuset modify command
  tuna: Add tests for cpuset modify command
  tuna: Fix test_modify_cpus_empty_result for kernel constraints
  tuna: Add --cpuset option to move command
  tuna: Add tests for tuna move --cpuset command
  tuna: Add --cpuset option to isolate command
  tuna: Add tests for isolate --cpuset functionality
  tuna: Document high-level workflow vs manual primitives for cpusets
  tuna: Add --cpuset filter option to show_threads command
  tuna: Add tests for show_threads --cpuset filter
  tuna: Enhance show_threads -G to display cpuset names
  tuna: Add tests for cpuset name display in show_threads -G
  tuna: Add --cpuset option to run command
  tuna: Add tests for run --cpuset functionality
  tuna: Update man page for cpusets and current functionality

 Makefile                           |   26 +-
 docs/tuna.8                        |  201 ++++-
 tests/README.md                    |  360 +++++++-
 tests/test_cpuset.py               |  944 +++++++++++++++++++
 tests/test_cpuset_cli.py           | 1344 ++++++++++++++++++++++++++++
 tests/test_process_blocklist.py    |  139 +++
 tests/test_show_threads_cgroups.py |  199 ++++
 tests/test_show_threads_cpuset.py  |  245 +++++
 tuna-cmd.py                        | 1192 +++++++++++++++++++++++-
 tuna/cpuset.py                     |  820 +++++++++++++++++
 tuna/cpuset_README.md              |  597 ++++++++++++
 tuna/help.py                       |   26 +-
 tuna/tuna.py                       |  187 +++-
 13 files changed, 6165 insertions(+), 115 deletions(-)
 create mode 100644 tests/test_cpuset.py
 create mode 100644 tests/test_cpuset_cli.py
 create mode 100644 tests/test_process_blocklist.py
 create mode 100644 tests/test_show_threads_cgroups.py
 create mode 100755 tests/test_show_threads_cpuset.py
 create mode 100644 tuna/cpuset.py
 create mode 100644 tuna/cpuset_README.md

-- 
2.54.0