mirror of https://github.com/kuhyx/testsAndMisc.git synced 2026-07-04 15:03:01 +02:00

Krzysztof kuhy Rudnicki 59e863f2a5 feat: Add shell script quality enforcement and polling optimization guidelines

- Add pre-commit hook (check_polling_antipatterns.sh) to detect fork-storm anti-patterns
- Update .pre-commit-config.yaml with no-polling-antipatterns hook registration
- Add comprehensive documentation (6 guides, 1000+ lines total)

Detects and blocks:
  * while true + sleep patterns (suggests event-driven I/O)
  * $(date +...) subprocess forks (suggests /proc/uptime or bash printf)
  * pgrep/xdotool in polling functions (expensive fork overhead)
  * aggressive polling (sleep < 1s causing fork storms)
  * heavy piped commands (| awk | grep | tr with multiple forks)

Documentation included:
  - SHELL_SCRIPT_QUALITY_GUIDELINES.md: 3-layer guide for developers/reviewers
  - SHELL_QUALITY_IMPLEMENTATION_SUMMARY.md: Technical implementation reference
  - COMPLETE_IMPLEMENTATION_SUMMARY.md: Full overview and integration guide
  - QUICK_REFERENCE_SHELL_QUALITY.md: Visual checklist and quick lookup
  - DELIVERABLES_INDEX.md: Index of all deliverables and next steps
  - shell.instructions.md: R1-R8 polling optimization rules (in ~/.copilot/instructions/)

System impact:
  - Prevents new scripts from introducing fork-storm regressions
  - Already active optimizations: network_monitor.sh zero-fork, battery 1s->5s, music adaptive sleep
  - Expected daily savings: ~1-2 CPU-hours from eliminated fork overhead

Related: Resolves previous fork-storm issue identified on May 3 causing 728k CPU-seconds

2026-05-03 21:42:49 +02:00

1.7 KiB

Raw Blame History

Quick Start: Polling Script Optimization

What Was Fixed

Your system was consuming 728,465 CPU-seconds (202 hours) just on the date command in a 5-hour window. This is a classic fork-storm anti-pattern from polling scripts.

Changes Made (3 files updated)

1. network_monitor.sh ✅

Replaced date +%s fork with /proc/uptime read (zero-fork)
Saves: 1 fork per polling cycle (~60-120ms per invocation)

2. i3blocks config ✅

Battery interval: 1s → 5s (80% fewer checks)
Saves: ~240 forks/min = 12 CPU-seconds/min

3. music_parallelism.sh ✅

Adaptive polling: 0.5s when active, 3s when idle
Saves: 83% fork reduction when system is idle

New Tools Available

cd /home/kuhy/testsAndMisc

# Diagnose inefficient scripts in your codebase
./run.sh --diagnose

# Profile system for 60 seconds to catch fork-storms
./run.sh --profile 60

# Generate today's usage report
./run.sh

Expected Impact

Estimated daily savings: 1-2 CPU-hours/day
Fork reduction: 83% when idle (from 2/sec to 0.33/sec)
Responsiveness: Improved (fewer context switches)

Verification

# Confirm changes applied:
grep -c "/proc/uptime" linux_configuration/i3-configuration/i3blocks/network_monitor.sh
grep "interval=5" linux_configuration/i3-configuration/i3blocks/config | grep battery
grep "sleep 3" linux_configuration/scripts/digital_wellbeing/music_parallelism.sh

Next Steps

After ~5 hours of normal system usage, run:

./run.sh --top 20

Compare against the original report—you should see the date command no longer in the top CPU consumers.

See POLLING_OPTIMIZATION_REPORT.md for detailed analysis and further optimization recommendations.

1.7 KiB Raw Blame History