<?php

declare(strict_types=1);

namespace App\Framework\Process;

use App\Framework\Core\ValueObjects\Duration;

/**
 * Interface für einen laufenden asynchronen Prozess.
 *
 * Ermöglicht die Verwaltung und Kontrolle eines Prozesses,
 * der im Hintergrund läuft.
 */
interface RunningProcess
{
    /**
     * Prüft, ob der Prozess noch läuft.
     *
     * @return bool True wenn der Prozess noch läuft
     */
    public function isRunning(): bool;

    /**
     * Gibt die Prozess-ID zurück.
     *
     * @return int Die Prozess-ID
     */
    public function getPid(): int;

    /**
     * Wartet bis der Prozess beendet ist und gibt das Ergebnis zurück.
     *
     * @param Duration|null $timeout Optionales Timeout
     * @return ProcessResult Das Ergebnis der Prozess-Ausführung
     *
     * @throws ProcessTimeoutException wenn das Timeout überschritten wird
     */
    public function wait(?Duration $timeout = null): ProcessResult;

    /**
     * Sendet ein Signal an den Prozess.
     *
     * @param int $signal Signal-Nummer (default: SIGTERM = 15)
     * @return void
     *
     * @throws ProcessException wenn das Signal nicht gesendet werden kann
     */
    public function signal(int $signal = 15): void;

    /**
     * Beendet den Prozess (SIGTERM).
     *
     * @return void
     */
    public function terminate(): void;

    /**
     * Beendet den Prozess forciert (SIGKILL).
     *
     * @return void
     */
    public function kill(): void;
}
