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\Manager;
20
21	use FastForward\Fork\Signal\Signal;
22	use FastForward\Fork\Worker\WorkerGroupInterface;
23	use FastForward\Fork\Worker\WorkerInterface;
24
25	/**
26	* Implementations of this interface MUST provide the orchestration layer responsible
27	* for spawning, supervising, signaling, and synchronizing worker processes.
28	* Implementations SHOULD ensure predictable lifecycle management and MUST expose
29	* enough behavior to distinguish master and worker execution contexts.
30	*
31	* The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
32	* "RECOMMENDED", "MAY", and "OPTIONAL" in this contract are to be interpreted as
33	* described in RFC 2119.
34	*/
35	interface ForkManagerInterface
36	{
37	/**
38	* Indicates whether the current runtime supports the library requirements.
39	*
40	* Implementations MUST validate the availability of the runtime capabilities
41	* required to manage worker processes correctly. The returned value SHALL
42	* reflect whether the execution environment is suitable for safe operation.
43	*
44	* @return bool true when the runtime environment supports the required process
45	*              control features; otherwise, false
46	*/
47	public function isSupported(): bool;
48
49	/**
50	* Forks one or more workers for the provided callback and returns them as a group.
51	*
52	* The callback MUST receive the current worker as its first argument.
53	* Implementations MUST create exactly the requested number of workers when the
54	* operation succeeds. If the runtime cannot complete the operation safely,
55	* implementations SHOULD fail explicitly rather than returning a partial and
56	* misleading result.
57	*
58	* @param callable(WorkerInterface): mixed $workerCallback callback executed
59	*                                                         inside each worker
60	*                                                         process
61	* @param int $workerCount number of workers to create for the callback
62	*
63	* @return WorkerGroupInterface a group representing the workers created for
64	*                              the provided callback
65	*/
66	public function fork(callable $workerCallback, int $workerCount = 1): WorkerGroupInterface;
67
68	/**
69	* Waits until all targeted workers finish.
70	*
71	* When no worker or group is provided, implementations MUST wait for every
72	* worker instantiated by this manager. Implementations SHALL block until the
73	* targeted workers have exited or have otherwise been fully reconciled by the
74	* manager lifecycle.
75	*
76	* @param WorkerInterface|WorkerGroupInterface ...$workers Workers and groups
77	*                                                         to wait for.
78	*
79	* @return void
80	*/
81	public function wait(WorkerInterface|WorkerGroupInterface ...$workers): void;
82
83	/**
84	* Sends a signal to all targeted workers.
85	*
86	* When no worker or group is provided, implementations MUST signal every
87	* worker instantiated by this manager. Implementations SHOULD ensure that the
88	* signal is delivered only to workers under their own control and MUST NOT
89	* silently target unrelated processes.
90	*
91	* @param Signal $signal signal to send to each targeted worker
92	* @param WorkerInterface|WorkerGroupInterface ...$workers Workers and groups
93	*                                                         to signal.
94	*
95	* @return void
96	*/
97	public function kill(
98	Signal $signal = Signal::Terminate,
99	WorkerInterface|WorkerGroupInterface ...$workers,
100	): void;
101
102	/**
103	* Returns the PID of the master process associated with this manager.
104	*
105	* The returned process identifier MUST correspond to the process recognized by
106	* the implementation as the master orchestration context.
107	*
108	* @return int the process identifier of the master process
109	*/
110	public function getMasterPid(): int;
111
112	/**
113	* Indicates whether the current execution context is the master process.
114	*
115	* Implementations MUST return true only when the current process matches the
116	* master process associated with the manager instance.
117	*
118	* @return bool true when the current process is the master process; otherwise,
119	*              false
120	*/
121	public function isMaster(): bool;
122
123	/**
124	* Indicates whether the current execution context is a worker process.
125	*
126	* Implementations SHOULD treat this result as the logical inverse of the
127	* master-process check whenever that model is valid for the implementation.
128	*
129	* @return bool true when the current process is executing as a worker;
130	*              otherwise, false
131	*/
132	public function isWorker(): bool;
133	}