v3.4.0

DOCS/FLAGS.md

@@ -49,6 +49,7 @@
 - `+v`, `--no-verbose`        : Decrease verbosity. Disables --stats.
 - `-V`, `--version`           : Prints forkrun version number
 -  `--stats`                  : Prints NUMA statistics to stderr (currently ignored for UMA)
+- `--tui`, `--progress`      : Opens a live telemetry dashboard (TUI) visualizing throughput, memory footprint, and per-node CPU/queue saturation. `--no-tui`/`--no-progress` disables it.
 
 ### ERROR HANDLING & RETRIES
 

META

@@ -1,2 +1,2 @@
 NAME: forkrun
-VERSION: v3.3.0
+VERSION: v3.4.0

UNIT_TESTS/test_c_plugins.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # =============================================================================
-# forkrun v3.3.0 - C Plugin Test Suite
+# forkrun v3.4.0 - C Plugin Test Suite
 # =============================================================================
 
 set -o pipefail
@@ -13,7 +13,7 @@ HEADER="${UNIT_TESTS_DIR}/../ring_loadables/forkrun_plugin.h"
 mkdir -p "$TEST_DIR"
 cd "$TEST_DIR"
 
-echo "=== forkrun v3.3.0 C Plugin Test Suite ==="
+echo "=== forkrun v3.4.0 C Plugin Test Suite ==="
 echo "UNIT_TESTS_DIR : $UNIT_TESTS_DIR"
 echo "FRUN_SCRIPT    : $FRUN_SCRIPT"
 

UNIT_TESTS/test_c_plugins_v2.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # =============================================================================
-# forkrun v3.3.0 - C Plugin Rigorous Test Suite
+# forkrun v3.4.0 - C Plugin Rigorous Test Suite
 # =============================================================================
 
 set -o pipefail
@@ -13,7 +13,7 @@ HEADER="${UNIT_TESTS_DIR}/../ring_loadables/forkrun_plugin.h"
 mkdir -p "$TEST_DIR"
 cd "$TEST_DIR"
 
-echo "=== forkrun v3.3.0 C Plugin Rigorous Test Suite ==="
+echo "=== forkrun v3.4.0 C Plugin Rigorous Test Suite ==="
 
 # Source frun
 . "$FRUN_SCRIPT"

UNIT_TESTS/test_frun.sh

@@ -549,7 +549,7 @@ run_test_regex "Dry run (-N)" \
 
 run_test "Version (-V)" \
   "frun -V" \
-  "forkrun v3.3.0"
+  "forkrun v3.4.0"
 
 # FIXED: Check for USAGE string explicitly without exact match
 run_test_regex "Help (--help)" \

UNIT_TESTS/test_frun.sh.txt

@@ -549,7 +549,7 @@ run_test_regex "Dry run (-N)" \
 
 run_test "Version (-V)" \
   "frun -V" \
-  "forkrun v3.3.0"
+  "forkrun v3.4.0"
 
 # FIXED: Check for USAGE string explicitly without exact match
 run_test_regex "Help (--help)" \

UNIT_TESTS/test_frun_comprehensive.sh

@@ -2883,6 +2883,297 @@
     fi
 fi
 
+# ============================================================================
+# SECTION R: v3.4.0 NEW FEATURES (TUI, SLURM, Halt, Sweeps)
+# ============================================================================
+print_section R "v3.4.0 New Features (TUI, SLURM, Halt, Sweeps)"
+
+# --- R1: TUI flag accepted and pipeline completes (headless safe) ---
+# Even without a /dev/tty, frun should gracefully skip the TUI and run normally.
+run_test_exact R "R1: TUI flag accepted and pipeline completes (headless safe)" \
+    "seq 10 | frun --tui -k printf '%s\n'" \
+    "$(seq 10)"
+
+# --- R2: SLURM SIGUSR1 triggers checkpoint and exit 138 ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_SLURM"; mkdir -p "$_MD"
+    seq 10000 > "$_MD/input.txt"; rm -f "$_MD/.forkrun_resume"
+
+    # FIXED: Added -s so sleep reads from stdin and actually sleeps, keeping frun alive.
+    # Use pgrep to find the cleanroom bash (child of FPID) and signal it directly
+    bash -c "source '$FRUN_SOURCE'; cd '$_MD'; cat input.txt | FORKRUN_PREEMPT_MODE=1 frun -k -s -l 1 sleep 0.1 & FPID=\$!; sleep 0.3; CPID=\$(ps -o pid= --ppid \$FPID 2>/dev/null | tr -d ' '); [[ -n \"\$CPID\" ]] && (( CPID = CPID + 2 )) && kill -USR1 \$CPID; wait \$FPID" \
+        > "$_MD/output.txt" 2>"$_MD/err.txt"
+    _REXIT=$?
+
+    if (( _REXIT == 138 )) && [[ -f "$_MD/.forkrun_resume" ]] && grep -q "Caught SIGUSR1" "$_MD/err.txt"; then
+        TEST_RESULTS["R2: SLURM SIGUSR1 triggers checkpoint and exit 138"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R2: SLURM SIGUSR1 triggers checkpoint and exit 138"
+    else
+        TEST_RESULTS["R2: SLURM SIGUSR1 triggers checkpoint and exit 138"]="FAIL"
+        TEST_ERRORS["R2: SLURM SIGUSR1 triggers checkpoint and exit 138"]="exit=$_REXIT, cp=$([[ -f "$_MD/.forkrun_resume" ]] && echo yes || echo no), err=$(cat "$_MD/err.txt" | tail -1)"
+        ((FAILED_TESTS++)); _print_result FAIL "R2: SLURM SIGUSR1 triggers checkpoint and exit 138" "exit=$_REXIT"
+    fi
+fi
+
+# --- R3: Auto halt on absolute fail count (--halt fail=2) ---
+# (No changes - apply the forkrun_ring.c fix above to make this pass)
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_HALT1"; mkdir -p "$_MD"
+    cat > "$_MD/funcs.sh" << 'FUNCEOF'
+crash_on_3_7() {
+    for a in "$@"; do
+        if [[ "$a" == "3" ]] || [[ "$a" == "7" ]]; then
+            exit 1
+        else
+            printf '%s\n' "$a"
+        fi
+    done
+}
+FUNCEOF
+
+    bash -c "source '$FRUN_SOURCE' && source '$_MD/funcs.sh' && seq 1 100 | FORKRUN_RETRY_LIMIT=0 FORKRUN_EXTRA_FUNCS='crash_on_3_7' frun -k -l 1 -E --halt fail=2 crash_on_3_7" \
+        > "$_MD/out.txt" 2>"$_MD/err.txt"
+    _RX=$?
+    _RERR=$(cat "$_MD/err.txt")
+
+    if (( _RX != 0 )) && echo "$_RERR" | grep -q "Halt condition met (2 failed batches)"; then
+        TEST_RESULTS["R3: Auto halt on absolute fail count (--halt fail=2)"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R3: Auto halt on absolute fail count (--halt fail=2)"
+    else
+        TEST_RESULTS["R3: Auto halt on absolute fail count (--halt fail=2)"]="FAIL"
+        TEST_ERRORS["R3: Auto halt on absolute fail count (--halt fail=2)"]="exit=$_RX, err=$(echo "$_RERR" | tail -1)"
+        ((FAILED_TESTS++)); _print_result FAIL "R3: Auto halt on absolute fail count (--halt fail=2)" "exit=$_RX"
+    fi
+fi
+
+# --- R4: Auto halt on percentage (--halt fail=50%) ---
+# FIXED: Moved FORKRUN_RETRY_LIMIT=0 to the frun side, increased lines to 1000 to trigger early.
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_HALT2"; mkdir -p "$_MD"
+    cat > "$_MD/funcs.sh" << 'FUNCEOF'
+crash_even() {
+    for a in "$@"; do
+        if (( a % 3 != 0 )); then
+            exit 1
+        else
+            printf '%s\n' "$a"
+        fi
+    done
+}
+FUNCEOF
+
+    bash -c "source '$FRUN_SOURCE' && source '$_MD/funcs.sh' && seq 1 1000 | FORKRUN_EXTRA_FUNCS='crash_even' FORKRUN_RETRY_LIMIT=0 frun -k -l 1 -E --halt fail=50% crash_even" \
+        > "$_MD/out.txt" 2>"$_MD/err.txt"
+    _Rx=$?
+    _RERR=$(cat "$_MD/err.txt")
+
+    if (( _Rx != 0 )) && echo "$_RERR" | grep -q "Halt condition met (50% failed batches)"; then
+        TEST_RESULTS["R4: Auto halt on percentage (--halt fail=50%)"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R4: Auto halt on percentage (--halt fail=50%)"
+    else
+        TEST_RESULTS["R4: Auto halt on percentage (--halt fail=50%)"]="FAIL"
+        TEST_ERRORS["R4: Auto halt on percentage (--halt fail=50%)"]="exit=$_Rx, err=$(echo "$_RERR" | tail -1)"
+        ((FAILED_TESTS++)); _print_result FAIL "R4: Auto halt on percentage (--halt fail=50%)" "exit=$_Rx"
+    fi
+fi
+
+# --- R5: Sweep inline args (:::) with {1}-{2} substitution ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _ROUT=$(bash -c "source '$FRUN_SOURCE' && frun echo {1}-{2} ::: a b c ::: 1 2 2>&1 | sort")
+    _REXP="a-1
+a-2
+b-1
+b-2
+c-1
+c-2"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R5: Sweep inline args (:::) with {1}-{2}"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R5: Sweep inline args (:::) with {1}-{2}"
+    else
+        TEST_RESULTS["R5: Sweep inline args (:::) with {1}-{2}"]="FAIL"
+        TEST_ERRORS["R5: Sweep inline args (:::) with {1}-{2}"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R5: Sweep inline args (:::) with {1}-{2}" "output mismatch"
+    fi
+fi
+
+# --- R6: Sweep inline args (:::) default args ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _ROUT=$(bash -c "source '$FRUN_SOURCE' && frun echo ::: a b c ::: 1 2 2>&1 | sort")
+    _REXP="a 1
+a 2
+b 1
+b 2
+c 1
+c 2"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R6: Sweep inline args (:::) default args"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R6: Sweep inline args (:::) default args"
+    else
+        TEST_RESULTS["R6: Sweep inline args (:::) default args"]="FAIL"
+        TEST_ERRORS["R6: Sweep inline args (:::) default args"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R6: Sweep inline args (:::) default args" "output mismatch"
+    fi
+fi
+
+# --- R7: Sweep file args (::::) default args ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_SWEEP2"; mkdir -p "$_MD"
+    printf "x\ny\nz\n" > "$_MD/f1.txt"
+    printf "100\n200\n" > "$_MD/f2.txt"
+
+    _ROUT=$(bash -c "source '$FRUN_SOURCE' && frun echo :::: '$_MD/f1.txt' :::: '$_MD/f2.txt' 2>&1 | sort")
+    _REXP="x 100
+x 200
+y 100
+y 200
+z 100
+z 200"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R7: Sweep file args (::::) default args"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R7: Sweep file args (::::) default args"
+    else
+        TEST_RESULTS["R7: Sweep file args (::::) default args"]="FAIL"
+        TEST_ERRORS["R7: Sweep file args (::::) default args"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R7: Sweep file args (::::) default args" "output mismatch"
+    fi
+fi
+
+# --- R8: Sweep --link zip mode ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _ROUT=$(bash -c "source '$FRUN_SOURCE' && frun --link echo ::: a b c ::: 1 2 3 2>&1 | sort")
+    _REXP="a 1
+b 2
+c 3"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R8: Sweep --link zip mode"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R8: Sweep --link zip mode"
+    else
+        TEST_RESULTS["R8: Sweep --link zip mode"]="FAIL"
+        TEST_ERRORS["R8: Sweep --link zip mode"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R8: Sweep --link zip mode" "output mismatch"
+    fi
+fi
+
+# --- R9: Sweep with bash function ---
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _ROUT=$(bash -c "source '$FRUN_SOURCE' && my_func() { echo \"\$1:\$2\"; }; frun my_func ::: a b ::: 1 2 2>&1 | sort" 2>/dev/null)
+    _REXP="a:1
+a:2
+b:1
+b:2"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R9: Sweep with bash function"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R9: Sweep with bash function"
+    else
+        TEST_RESULTS["R9: Sweep with bash function"]="FAIL"
+        TEST_ERRORS["R9: Sweep with bash function"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R9: Sweep with bash function" "output mismatch"
+    fi
+fi
+
+# --- R10: SLURM SIGTERM triggers checkpoint and exit 143 ---
+# Verifies that standard SLURM scancel/preemption (SIGTERM) is caught and handled identically to SIGUSR1
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_SLURM_TERM"; mkdir -p "$_MD"
+    seq 10000 > "$_MD/input.txt"; rm -f "$_MD/.forkrun_resume"
+
+    bash -c "source '$FRUN_SOURCE'; cd '$_MD'; cat input.txt | FORKRUN_PREEMPT_MODE=1 frun -k -s -l 1 sleep 0.1 & FPID=\$!; sleep 0.3; CPID=\$(ps -o pid= --ppid \$FPID 2>/dev/null | tr -d ' '); [[ -n \"\$CPID\" ]] && (( CPID = CPID + 2 )) && kill -TERM \$CPID 2>/dev/null || kill -TERM \$FPID 2>/dev/null; wait \$FPID" \
+        > "$_MD/output.txt" 2>"$_MD/err.txt"
+    _REXIT=$?
+
+    if (( _REXIT == 143 )) && [[ -f "$_MD/.forkrun_resume" ]]; then
+        TEST_RESULTS["R10: SLURM SIGTERM triggers checkpoint and exit 143"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R10: SLURM SIGTERM triggers checkpoint and exit 143"
+    else
+        TEST_RESULTS["R10: SLURM SIGTERM triggers checkpoint and exit 143"]="FAIL"
+        TEST_ERRORS["R10: SLURM SIGTERM triggers checkpoint and exit 143"]="exit=$_REXIT, cp=$([[ -f "$_MD/.forkrun_resume" ]] && echo yes || echo no)"
+        ((FAILED_TESTS++)); _print_result FAIL "R10: SLURM SIGTERM triggers checkpoint and exit 143" "exit=$_REXIT"
+    fi
+fi
+
+# --- R11: GNU Parallel Halt Syntax (--halt now,2) ---
+# Verifies the C-level parser fix correctly identifies the "now," prefix without "fail="
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _MD="$TEST_DIR/R_HALT3"; mkdir -p "$_MD"
+    cat > "$_MD/funcs.sh" << 'FUNCEOF'
+crash_on_3_7() {
+    for a in "$@"; do
+        if [[ "$a" == "3" ]] || [[ "$a" == "7" ]]; then
+            exit 1
+        else
+            printf '%s\n' "$a"
+        fi
+    done
+}
+FUNCEOF
+
+    bash -c "source '$FRUN_SOURCE' && source '$_MD/funcs.sh' && seq 1 10 | FORKRUN_RETRY_LIMIT=0 FORKRUN_EXTRA_FUNCS='crash_on_3_7' frun -k -l 1 -E --halt now,2 crash_on_3_7" \
+        > "$_MD/out.txt" 2>"$_MD/err.txt"
+    _RX=$?
+    _RERR=$(cat "$_MD/err.txt")
+
+    if (( _RX != 0 )) && echo "$_RERR" | grep -q "Halt condition met (2 failed batches)"; then
+        TEST_RESULTS["R11: GNU Halt syntax (--halt now,2) triggers abort"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R11: GNU Halt syntax (--halt now,2) triggers abort"
+    else
+        TEST_RESULTS["R11: GNU Halt syntax (--halt now,2) triggers abort"]="FAIL"
+        TEST_ERRORS["R11: GNU Halt syntax (--halt now,2) triggers abort"]="exit=$_RX, err=$(echo "$_RERR" | tail -1)"
+        ((FAILED_TESTS++)); _print_result FAIL "R11: GNU Halt syntax (--halt now,2) triggers abort" "exit=$_RX"
+    fi
+fi
+
+# --- R12: Sweep file args from stdin (:::: -) ---
+# Verifies the mapfile /dev/stdin branch works perfectly
+if in_section R; then
+    ((TOTAL_TESTS++))
+    _ROUT=$(printf "x\ny\nz\n" | bash -c "source '$FRUN_SOURCE' && frun echo ::: a b :::: - 2>&1 | sort")
+    _REXP="a x
+a y
+a z
+b x
+b y
+b z"
+    if [[ "$_ROUT" == "$_REXP" ]]; then
+        TEST_RESULTS["R12: Sweep file args from stdin (:::: -)"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R12: Sweep file args from stdin (:::: -)"
+    else
+        TEST_RESULTS["R12: Sweep file args from stdin (:::: -)"]="FAIL"
+        TEST_ERRORS["R12: Sweep file args from stdin (:::: -)"]="out: $_ROUT"
+        ((FAILED_TESTS++)); _print_result FAIL "R12: Sweep file args from stdin (:::: -)" "output mismatch"
+    fi
+fi
+
+# --- R13: Sweep --link zip mode truncates uneven arrays safely ---
+# Verifies the bash orchestrator safely truncates to the shortest length and warns the user
+if in_section R; then
+    ((TOTAL_TESTS++))
+    bash -c "source '$FRUN_SOURCE' && frun --link echo ::: 1 2 3 4 ::: a b" > "$TEST_DIR/r13_out.txt" 2> "$TEST_DIR/r13_err.txt"
+    _ROUT=$(sort "$TEST_DIR/r13_out.txt")
+    _RERR=$(cat "$TEST_DIR/r13_err.txt")
+    _REXP="1 a
+2 b"
+
+    # FIXED: Added -i to grep to handle the capital 'T' in "Truncating"
+    if [[ "$_ROUT" == "$_REXP" ]] && echo "$_RERR" | grep -qi "truncating combinations to the shortest length (2)"; then
+        TEST_RESULTS["R13: Sweep --link truncates uneven arrays safely"]="PASS"; ((PASSED_TESTS++))
+        _print_result PASS "R13: Sweep --link truncates uneven arrays safely"
+    else
+        TEST_RESULTS["R13: Sweep --link truncates uneven arrays safely"]="FAIL"
+        TEST_ERRORS["R13: Sweep --link truncates uneven arrays safely"]="out: $_ROUT, err: $_RERR"
+        ((FAILED_TESTS++)); _print_result FAIL "R13: Sweep --link truncates uneven arrays safely" "output or warning mismatch"
+    fi
+fi
+
 # ============================================================================
 # SUMMARY
 # ============================================================================