StackPractices
intermediate Por Mathias Paulenko

Control de Jobs Paralelos

Cómo controlar jobs de Bash en paralelo una vez que corren: recolectar códigos de salida, reintentar fallos, aplicar timeouts y reanudar lotes interrumpidos.

Visión General

Hacer que los comandos corran en paralelo es la mitad fácil — xargs -P, GNU parallel o un loop con & lo resuelven en una línea (cubierto en Ejecución Paralela en Bash). La mitad difícil empieza cuando los jobs ya corren: ¿cuáles fallaron? ¿cuáles merecen reintento? ¿qué relanzás tras un Ctrl+C a la mitad de un lote de 500 jobs?

Esta receta trata de esa segunda mitad: códigos de salida por job, timeouts, reintentos con backoff y el joblog de GNU parallel que lo ata todo.

Cuándo Usar

  • Un lote donde los jobs individuales pueden fallar y necesitás saber exactamente cuáles.
  • Tareas inestables — llamadas de red, APIs con rate limit — que merecen un reintento antes de darse por vencido.
  • Pipelines largos que deben reanudar donde quedaron en vez de empezar de cero.
  • Jobs que pueden colgarse y necesitan un timeout duro para que una tarea atascada no bloquee el lote.

Si solo necesitás “correr estos comandos a la vez”, empezá con la receta de ejecución básica y volvé acá cuando el lote crezca.

Solución

Un wrapper completo de control de jobs: GNU parallel ejecuta el trabajo, escribe un joblog por corrida y un reporte te dice qué falló.

#!/usr/bin/env bash
set -euo pipefail

MAX_JOBS="${1:-4}"
INPUT_FILE="${2:-jobs.txt}"
LOG_DIR="${3:-./parallel-logs}"

mkdir -p "$LOG_DIR"

process_task() {
    local task="$1"
    echo "Processing $task"
    sleep "$((RANDOM % 3 + 1))"
    echo "Done $task"
}
export -f process_task

# Correr con joblog: queda registrado exit code, duración y comando de cada job
parallel --jobs "$MAX_JOBS" \
    --joblog "$LOG_DIR/joblog.txt" \
    --timeout 300 \
    --halt soon,fail=20% \
    process_task {} \
    < "$INPUT_FILE"

# Resumen: columnas del joblog = Seq Host Starttime Runtime Send Receive Exitval Signal Command
awk 'NR>1 {codes[$7]++} END {for (c in codes) printf "Exit %s: %d jobs\n", c, codes[c]}' \
    "$LOG_DIR/joblog.txt"

# Listar lo que falló para relanzar solo eso
awk 'NR>1 && $7!=0 {print $NF}' "$LOG_DIR/joblog.txt" > "$LOG_DIR/failed.txt" || true
if [[ -s "$LOG_DIR/failed.txt" ]]; then
    echo "Jobs fallidos escritos en $LOG_DIR/failed.txt"
fi

Explicación

El joblog es el truco central. GNU parallel agrega una fila por job — cuándo arrancó, cuánto tardó, su valor de salida y el comando exacto. Ese archivo convierte un lote opaco en algo que podés auditar, post-procesar con awk y reanudar.

Tres propiedades lo hacen seguro para lotes reales:

  • Los códigos de salida sobreviven. Cada fila guarda el exit value del hijo, así que un job fallido no puede esconderse entre 200 éxitos. xargs -P solo te dice “algo falló” vía exit code 123; el joblog te dice qué falló.
  • Los timeouts son por job. --timeout 300 mata una tarea colgada, no el lote. El job matado queda en el joblog con señal 15, así que lo distinguís de un fallo limpio.
  • --halt soon,fail=20% es tu cortacircuitos. Si más del 20% de los jobs falla, parallel deja de encolar trabajo nuevo pero deja terminar los que corren. Ajustalo o quitalo para lotes donde el fallo parcial es esperado.
Flujo de control de jobs. Un archivo de jobs alimenta un pool de workers. Cada job corre bajo timeout con reintentos, escribe su resultado en el joblog, y una agregación final reporta éxitos y jobs fallidos para relanzar.

Variantes

HerramientaMecanismo de controlIdeal para
GNU parallel--joblog, --resume, --resume-failed, --retriesLotes en producción; pipelines reanudables
xargs -PArchivos de resultado por job (abajo)Sistemas donde parallel no está instalado
Background jobs + waitTracking de PID con $! + wait "$pid"Lotes chicos, cero dependencias
Python multiprocessingCódigos de salida en resultados de pool.mapJobs ya envueltos en Python

Lo que funciona

  1. Escribí un archivo de resultado por job. Cuando no hay joblog, un archivo task_result por job es el equivalente casero — y sobrevive a los crashes.
  2. Reintentá con backoff, no con loops. Las tareas inestables merecen 2–3 intentos con demoras crecientes, y después un FAILED limpio en el reporte.
  3. Mantené el archivo de input como fuente de verdad. wc -l jobs.txt vs. conteo de archivos de resultado te dice si algo se saltó.
  4. Logueá con el identificador del job. Prefijá la salida con el nombre de la tarea; te lo vas a agradecer al debuggear un job entre cientos.
  5. Limpiá el estado temporal al salir. trap + mktemp -d evita que los directorios de resultados se filtren a la próxima corrida.

El tutorial oficial de GNU Parallel cubre --joblog, --resume y --retries en profundidad si querés la referencia completa de flags.

Errores Comunes

  1. Confiar solo en el exit code de xargs. -P devuelve 123 si algún hijo falló — sin decir cuál. Recolectá el estado por job explícitamente.
  2. Reintentar jobs no idempotentes. Si una tarea tiene efectos secundarios, un reintento puede aplicarlos dos veces. Marcá qué jobs son seguros de relanzar.
  3. Semáforos con sleep en bucle. Encuestar jobs -r en un bucle ocupado gasta CPU; wait -n (Bash 4.3+) bloquea hasta que se libera un slot.
  4. Timeout como único modo de fallo. Un job que sale con 1 en 100ms no está colgado — distinguí señales de códigos de salida en tu reporte.
  5. Reanudar sin joblog. --resume necesita el joblog de la corrida interrumpida; sin él, estás relanzando todo.

Soluciones Avanzadas

GNU parallel: reanudar un lote interrumpido

--resume lee el joblog y salta los jobs que ya salieron con 0. --resume-failed además relanza los que fallaron — el comando estándar de “terminar el lote”.

#!/usr/bin/env bash
set -euo pipefail

LOG_DIR="${1:-./parallel-logs}"
INPUT_FILE="${2:-jobs.txt}"

process_task() {
    local task="$1"
    echo "Processing $task"
    sleep "$((RANDOM % 3 + 1))"
}
export -f process_task

# Relanzar solo lo que no terminó limpio la última vez
parallel --jobs 4 \
    --joblog "$LOG_DIR/joblog.txt" \
    --resume-failed \
    --timeout 300 \
    process_task {} \
    < "$INPUT_FILE"

xargs: archivos de resultado por job

¿Sin GNU parallel? Dale a cada job su propio archivo de resultado y agregá al final. basename hace la limpieza de nombre que {//} haría en parallel — xargs -I {} no soporta {//}.

#!/usr/bin/env bash
set -euo pipefail

MAX_JOBS="${1:-4}"
INPUT_FILE="${2:-jobs.txt}"
RESULTS_DIR=$(mktemp -d)
trap 'rm -rf "$RESULTS_DIR"' EXIT

process_with_exit() {
    local task="$1"
    local result_file="$2"
    sleep "$((RANDOM % 3 + 1))"
    if (( RANDOM % 10 == 0 )); then
        echo "FAIL" > "$result_file"
        return 1
    fi
    echo "OK" > "$result_file"
    return 0
}
export -f process_with_exit
export RESULTS_DIR

xargs -P "$MAX_JOBS" -I {} bash -c '
    task="{}"
    process_with_exit "$task" "$RESULTS_DIR/$(basename "$task")_result" || true
' < "$INPUT_FILE"

TOTAL=$(wc -l < "$INPUT_FILE")
SUCCESS=$(grep -l "OK" "$RESULTS_DIR"/*_result 2>/dev/null | wc -l)
echo "Total: $TOTAL, Éxito: $SUCCESS, Fallidos: $((TOTAL - SUCCESS))"

Reintentos con backoff exponencial

Envolvé la tarea en una función de reintento y dejá que parallel la distribuya. timeout le da a cada intento un techo duro; el backoff le da aire a servicios con rate limit.

#!/usr/bin/env bash
set -euo pipefail

MAX_JOBS="${1:-4}"
MAX_RETRIES="${2:-3}"
TIMEOUT="${3:-60}"
INPUT_FILE="${4:-jobs.txt}"

process_task() {
    local task="$1"
    # Reemplazar con trabajo real; debe tener éxito al reintentar
    sleep "$((RANDOM % 3 + 1))"
    (( RANDOM % 3 != 0 ))  # falla ~1 de 3 para demo
}
export -f process_task

run_with_retry() {
    local task="$1"
    local attempt=1

    while (( attempt <= MAX_RETRIES )); do
        if timeout "$TIMEOUT" bash -c 'process_task "$1"' _ "$task"; then
            echo "ÉXITO: $task (intento $attempt)"
            return 0
        fi
        echo "REINTENTO: $task (falló intento $attempt)" >&2
        ((attempt++))
        sleep "$((2 ** (attempt - 1)))"  # 2s, 4s, 8s...
    done

    echo "FALLÓ: $task después de $MAX_RETRIES intentos"
    return 1
}
export -f run_with_retry
export MAX_RETRIES TIMEOUT

parallel --jobs "$MAX_JOBS" run_with_retry {} < "$INPUT_FILE"

El loop de reintentos es una pequeña máquina de estados — conviene tenerlo claro antes de tocarlo:

Loop de reintentos con backoff exponencial. Cada intento corre el job bajo timeout. Si falla, el contador crece; mientras queden reintentos, el worker duerme 2^n segundos y vuelve a probar. Cuando se agotan, el job queda marcado FAILED para una pasada de relanzado.

El comando timeout es GNU coreutils — en macOS instalá coreutils y llamalo gtimeout.

Comparación con multiprocessing de Python

Cuando el pipeline ya vive en Python, multiprocessing.Pool te da el mismo control de forma nativa — los códigos de salida vuelven en los resultados de pool.map y no hay quoting que pelear. Acá cada línea de jobs.txt es un comando de shell completo:

import multiprocessing
import shutil
import subprocess
import time
from pathlib import Path

# Resolver bash explícitamente: en Windows, CreateProcess encontraría
# el lanzador de WSL en System32 antes que el bash real del PATH
BASH = shutil.which("bash") or shutil.which("sh") or "bash"

def run_task(task: str) -> tuple[str, int, float]:
    start = time.time()
    result = subprocess.run(
        [BASH, "-c", task],
        capture_output=True,
        text=True,
        timeout=300,
    )
    return task, result.returncode, time.time() - start

def main():
    tasks = Path("jobs.txt").read_text().strip().split("\n")
    max_workers = min(4, multiprocessing.cpu_count())

    with multiprocessing.Pool(max_workers) as pool:
        results = pool.map(run_task, tasks)

    succeeded = sum(1 for _, code, _ in results if code == 0)
    print(f"Total: {len(results)}, Éxito: {succeeded}, Fallidos: {len(results) - succeeded}")

    for task, code, elapsed in results:
        status = "OK" if code == 0 else f"FAIL (exit {code})"
        print(f"  {task}: {status} ({elapsed:.1f}s)")

if __name__ == "__main__":
    main()

find + xargs: procesamiento de archivos en lote

El clásico fan-out paralelo de archivos — notá -print0 | xargs -0 para que los nombres con espacios no rompan, y cada {} entre comillas dentro de los wrappers sh -c:

#!/usr/bin/env bash
set -euo pipefail

MAX_JOBS="${1:-$(nproc)}"
TARGET_DIR="${2:-.}"

# Comprimir todos los archivos log en paralelo
find "$TARGET_DIR" -type f -name "*.log" -print0 | \
    xargs -0 -P "$MAX_JOBS" -I {} gzip -9 "{}"

# Generar checksums en paralelo
find "$TARGET_DIR" -type f -print0 | \
    xargs -0 -P "$MAX_JOBS" -I {} sh -c 'sha256sum "{}" > "{}.sha256"'

# Redimensionar imágenes en paralelo (requiere ImageMagick)
find "$TARGET_DIR" -type f \( -name "*.jpg" -o -name "*.png" \) -print0 | \
    xargs -0 -P "$MAX_JOBS" -I {} sh -c 'convert "{}" -resize 50% "{}.thumb"'

Código companion: El repo companion de bash-parallel-job-execution tiene los cuatro scripts de control de jobs como archivos ejecutables.

Preguntas frecuentes

¿Cómo relanzo solo los jobs que fallaron?

Con GNU parallel, mantené --joblog en la corrida original y relanzá con --resume-failed. Sin él, escribí un archivo de resultado por job y alimentá los faltantes/fallidos como nuevo archivo de input.

¿Cómo recolecto códigos de salida de jobs de xargs?

xargs -P solo devuelve 123 cuando algo falla — no qué falló. Hacé que cada job escriba un archivo de resultado (OK/FAIL más el exit code) y agregalos, o cambiá al joblog de GNU parallel para un registro incorporado.

¿Cómo freno un job colgado sin matar todo el lote?

Dale a cada job su propio timeout: --timeout de GNU parallel o envolvé el comando en timeout 60. El job matado aparece con señal 15 en el joblog, así que los timeouts se distinguen de fallos reales.

¿Cuál es la diferencia entre xargs y GNU parallel para control de jobs?

xargs distribuye trabajo; ahí termina. GNU parallel agrega la capa de control: joblog, reanudación, salida ordenada, resultados por job, ejecución remota. Para cualquier cosa más allá de "correr N a la vez", parallel justifica su dependencia.

¿Cómo veo qué jobs siguen corriendo?

jobs -l lista los jobs en background de la shell actual, ps aux | grep <comando> a nivel sistema, y column -t < joblog.txt muestra el progreso en vivo de GNU parallel — las filas aparecen a medida que los jobs terminan.