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\Worker;
20
21	use FastForward\Fork\Signal\Signal;
22
23	/**
24	* Defines the contract for a single worker process.
25	*
26	* Implementations MUST represent a process created and managed by a fork manager.
27	* A worker SHALL expose its lifecycle state, execution result, and communication
28	* channels (output and error output).
29	*
30	* Consumers MAY interact with a worker to observe its execution, wait for its
31	* completion, or send signals to control its lifecycle.
32	*
33	* Implementations SHOULD ensure that state access is safe and consistent across
34	* process boundaries.
35	*
36	* The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD",
37	* "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as
38	* described in RFC 2119.
39	*/
40	interface WorkerInterface
41	{
42	/**
43	* Returns the process identifier (PID) of this worker.
44	*
45	* The PID MUST uniquely identify the worker process within the operating system.
46	*
47	* @return int the worker process identifier
48	*/
49	public function getPid(): int;
50
51	/**
52	* Indicates whether this worker is still running.
53	*
54	* Implementations MUST return true while the worker process is active and
55	* has not yet terminated.
56	*
57	* @return bool true if the worker is running; otherwise false
58	*/
59	public function isRunning(): bool;
60
61	/**
62	* Returns the raw status reported by the operating system, when available.
63	*
64	* Implementations MAY return null if the worker has not yet terminated or if
65	* the status is not available.
66	*
67	* @return int|null the raw process status or null if unavailable
68	*/
69	public function getStatus(): ?int;
70
71	/**
72	* Returns the worker exit code when it exits normally.
73	*
74	* Implementations MUST return a value between 0 and 255 when the worker
75	* terminates normally. If the worker has not exited or was terminated by a
76	* signal, null SHALL be returned.
77	*
78	* @return int|null the exit code or null if not applicable
79	*/
80	public function getExitCode(): ?int;
81
82	/**
83	* Returns the signal that terminated the worker.
84	*
85	* Implementations MUST return the corresponding signal when the worker was
86	* terminated by a signal. If the worker exited normally or has not yet
87	* terminated, null SHALL be returned.
88	*
89	* @return Signal|null the terminating signal or null if not applicable
90	*/
91	public function getTerminationSignal(): ?Signal;
92
93	/**
94	* Returns the captured standard output produced by this worker.
95	*
96	* Implementations MAY return partial output while the worker is still
97	* running. Once the worker has terminated, the returned output SHOULD be
98	* complete.
99	*
100	* @return string the captured output
101	*/
102	public function getOutput(): string;
103
104	/**
105	* Returns the captured error output produced by this worker.
106	*
107	* Implementations MAY return partial error output while the worker is still
108	* running. Once the worker has terminated, the returned output SHOULD be
109	* complete.
110	*
111	* @return string the captured error output
112	*/
113	public function getErrorOutput(): string;
114
115	/**
116	* Waits until this worker has finished execution.
117	*
118	* Implementations MUST block the caller until the worker process has
119	* terminated or has been fully reconciled by the manager.
120	*
121	* @return void
122	*/
123	public function wait(): void;
124
125	/**
126	* Sends a signal to this worker.
127	*
128	* Implementations MUST attempt to deliver the provided signal to the worker
129	* process. If the worker is no longer running, the implementation MAY ignore
130	* the request.
131	*
132	* @param Signal $signal the signal to send to the worker
133	*
134	* @return void
135	*/
136	public function kill(Signal $signal = Signal::Terminate): void;
137	}