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 Countable;
22	use FastForward\Fork\Manager\ForkManagerInterface;
23	use FastForward\Fork\Signal\Signal;
24	use IteratorAggregate;
25	use Traversable;
26
27	/**
28	* Defines an immutable group of workers.
29	*
30	* Implementations MUST represent a read-only collection of workers that were
31	* created by the same manager instance. The group SHALL provide consistent
32	* access, iteration, and batch operations over the underlying workers.
33	*
34	* Consumers MAY use this abstraction to coordinate multiple workers as a single
35	* unit without managing them individually.
36	*
37	* @extends IteratorAggregate<int, WorkerInterface>
38	*/
39	interface WorkerGroupInterface extends Countable, IteratorAggregate
40	{
41	/**
42	* Returns the manager that created this worker group.
43	*
44	* The returned manager MUST be the same instance responsible for all workers
45	* contained in this group.
46	*
47	* @return ForkManagerInterface the manager associated with this group
48	*/
49	public function getManager(): ForkManagerInterface;
50
51	/**
52	* Returns all tracked workers.
53	*
54	* The returned array MUST contain all workers belonging to this group and
55	* SHALL be indexed by their process identifiers (PID).
56	*
57	* @return array<int, WorkerInterface> all workers in the group
58	*/
59	public function all(): array;
60
61	/**
62	* Returns a worker by its PID.
63	*
64	* If no worker exists for the given PID, the method MUST return null.
65	*
66	* @param int $pid the process identifier of the worker
67	*
68	* @return WorkerInterface|null the matching worker or null if not found
69	*/
70	public function get(int $pid): ?WorkerInterface;
71
72	/**
73	* Waits until all workers in this group have finished.
74	*
75	* Implementations MUST block until all workers have terminated or have been
76	* fully reconciled by the manager.
77	*
78	* @return void
79	*/
80	public function wait(): void;
81
82	/**
83	* Sends a signal to all workers in this group.
84	*
85	* Implementations MUST ensure that the signal is delivered only to workers
86	* belonging to this group.
87	*
88	* @param Signal $signal the signal to send to each worker
89	*
90	* @return void
91	*/
92	public function kill(Signal $signal = Signal::Terminate): void;
93
94	/**
95	* Returns the workers that are currently running.
96	*
97	* Implementations MUST return only workers whose execution has not yet
98	* completed.
99	*
100	* @return array<int, WorkerInterface> running workers
101	*/
102	public function getRunning(): array;
103
104	/**
105	* Returns the workers that are no longer running.
106	*
107	* Implementations MUST return only workers that have already terminated or
108	* are no longer active.
109	*
110	* @return array<int, WorkerInterface> stopped workers
111	*/
112	public function getStopped(): array;
113
114	/**
115	* Returns an iterator for the tracked workers.
116	*
117	* The iterator MUST provide read-only traversal over the worker collection.
118	*
119	* @return Traversable<int, WorkerInterface> iterator over workers
120	*/
121	public function getIterator(): Traversable;
122
123	/**
124	* Returns the number of tracked workers.
125	*
126	* @return int total number of workers in the group
127	*/
128	public function count(): int;
129	}