1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of fast-forward/fork.
7	*
8	* This source file is subject to the license bundled
9	* with this source code in the file LICENSE.
10	*
11	* @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12	* @license   https://opensource.org/licenses/MIT MIT License
13	*
14	* @see       https://github.com/php-fast-forward/fork
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\Fork\Signal;
20
21	use FastForward\Fork\Manager\ForkManagerInterface;
22
23	/**
24	* Defines the contract for manager-owned signal handlers.
25	*
26	* Implementations MUST define which signals they subscribe to and MUST provide
27	* a callable handler capable of reacting to those signals within the context of
28	* a fork manager.
29	*
30	* Signal handlers SHOULD be idempotent and MUST be safe to execute multiple
31	* times, as signal delivery MAY occur repeatedly or concurrently depending on
32	* the runtime environment.
33	*
34	* Implementations MAY normalize or reinterpret signals before acting upon them,
35	* provided that the resulting behavior remains predictable for consumers.
36	*
37	* The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD",
38	* "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as
39	* described in RFC 2119.
40	*/
41	interface SignalHandlerInterface
42	{
43	/**
44	* Returns the signals handled by this handler.
45	*
46	* Implementations MUST return a non-empty list of signals that the manager
47	* will subscribe to on behalf of this handler.
48	*
49	* @return array<int, Signal> the list of handled signals
50	*/
51	public function signals(): array;
52
53	/**
54	* Handles a signal for the provided manager.
55	*
56	* Implementations MUST execute the handling logic for the given signal in
57	* the context of the provided manager. The handler MAY trigger side effects
58	* such as propagating signals to workers, performing cleanup, or terminating
59	* the process.
60	*
61	* @param ForkManagerInterface $manager manager that received the signal
62	* @param Signal $signal signal that was received or normalized by the manager
63	*
64	* @return void
65	*/
66	public function __invoke(ForkManagerInterface $manager, Signal $signal): void;
67	}