[Console] Add AlarmableCommandInterface and console.alarm event

[HypeMC]

Q	A
Branch?	7.1
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues	Fix #47920
License	MIT

Part of #53508

This PR introduces a new AlarmableCommandInterface and a console.alarm event. A command implementing this interface will automatically subscribe to the SIGALRM signal and dispatch an alarm at the specified interval:

#[AsCommand('app:alarm')]
class AlarmCommandCopy extends Command implements AlarmableCommandInterface, SignalableCommandInterface
{
    private bool $run = true;
    private int $count = 0;
    private OutputInterface $output;

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $this->output = $output;

        while ($this->run) {
            $this->count++;
            $output->writeln('execute '.$this->count);
            sleep(1);
        }

        $output->writeln('Done');

        return Command::SUCCESS;
    }

    public function getAlarmInterval(InputInterface $input): int
    {
        return 10;
    }

    public function handleAlarm(int|false $previousExitCode = 0): false|int
    {
        $this->count = 0;
        $this->output->writeln('handleAlarm');

        return false;
    }

    public function getSubscribedSignals(): array
    {
        return [\SIGINT];
    }

    public function handleSignal(int $signal, false|int $previousExitCode = 0): int|false
    {
        if (\SIGINT === $signal) {
            $this->run = false;
        }

        return false;
    }
}

When a command implements both the AlarmableCommandInterface and the SignalableCommandInterface, the handleSignal() method will not be called for a SIGALRM signal.

The console.alarm event is dispatched on every SIGALRM signal:

#[AsEventListener(event: 'console.alarm')]
final class ConsoleAlarmListener
{
    public function __invoke(ConsoleAlarmEvent $event): void
    {
        $event->getOutput()->writeln('ConsoleAlarmListener');
    }
}

[stof]

you cannot add mandatory arguments in a method signature through such BC layer, because the child class is not allowed to add them as mandatory arguments.

Btw, changing the subscribed signals based on the output looks weird to me. What is the use case for it ? Is this worth a BC break ?

[HypeMC]

The more I thought about it, the less sense it made to me as well. I initially had a use case for #53508, but I've since found a better approach, and now I can't really think of a good use case. Therefore, I've removed the entire commit. If an actual use case comes up in the future, it can be added then. I've also removed the $output argument from getAlarmTime() as it was also useless.

[stof]

Making the TraceableCommand implement AlarmableCommandInterface means that in dev, all commands will register this SIGALRM (even when they are not alarmable). Is this expected ?

[HypeMC]

No, good catch, I've totally missed that one. I've added a TraceableAlarmableCommand, so this should no longer be an issue. I'm not sure if this is the best approach, but I couldn't think of any other.

[stof]

this will never be called in dev when a SignalableCommand asks for SIGALRM because of the TraceableCommand wrapping it and implementing AlarmableCommandInterface. This means this PR is currently a BC break.

[stof]

Same issue here regarding TraceableCommand.

[stof]

Is the command actually dispatching SIGALRM signals ? The rest of the code gives me the impression that it listens to those signals.

[HypeMC]

Fixed

[valtzu]

Btw, SIGALRM has the same effect as any other signal – it interrupts sleep & usleep. According to docs, one should check based on return code if the sleep was interrupted but I doubt many do that – and usleep returns void so for that it's impossible.

So if a command logic f.e. includes sleep(30); or $clock->sleep(30);, it will only sleep until next alarm, potentially causing unexpected behavior.

---

Another (old) thing I found that using SIGALRM to provide timer functionality may result in deadlock – not sure if it's still relevant (or if it ever was, for php).

[ro0NL]

from the original issue, it was taken into account:

    $left = sleep(10);
    while ($left > 0) {
        $left = sleep($left);
    }

i think this is a reasonable workaround (but needs documentation), even if it's not supported on windows (that's a PHP API issue/bug), and should not block this PR

for Linux, we could even fix/abstract it in $clock->sleep() (as per above example), either optionally or out-of-the-box