Coordinates the lifecycle of worker processes using process forking.
Description
This class acts as the central orchestrator responsible for:
- Creating worker processes
- Managing their lifecycle and state
- Handling inter-process communication via streams
- Propagating and handling system signals
Implementations MUST ensure that process control functions are available. The manager SHALL operate as a master process and MUST NOT be reused inside worker processes.
Interfaces
Implementations of this interface MUST provide the orchestration layer responsible for spawning, supervising, signaling, and synchronizing worker processes.
Constants
POSIX error code for interrupted system calls.
POSIX error code for missing child processes.
Properties
PID of the master process that instantiated this manager.
Stores runtime state objects associated with each worker.
Stores all worker instances indexed by their process ID (PID).
Methods
Initializes the manager, validates environment support, and registers signal handlers.
Forks one or more worker processes.
Retrieves the PID of the master process.
Determines whether the current process is the master process.
Determines whether the current environment supports process forking.
Determines whether the current process is a worker process.
Sends a signal to one or more workers.
Waits for one or more workers or worker groups to finish execution.
Ensures that a worker belongs to this manager.
Collects terminated child processes.
Detects the current process ID (PID).
Drains output buffers from all running workers.
Checks if any target worker is still running.
Determines if a wait error was caused by an interrupted system call.
Determines if there are no remaining child processes.
Sends a signal to all provided workers.
Registers signal handlers for all configured signals.
Resolves worker and group inputs into a unique set of workers.
Waits for the provided workers and processes their output streams.
private
LoggerInterface|null
$logger
=
null
PID of the master process that instantiated this manager.
private
int
$masterPid
Description
This value MUST remain immutable after initialization.
private
SignalHandlerInterface
$signalHandler
=
new DefaultSignalHandler()
Stores runtime state objects associated with each worker.
private
array<int, WorkerState>
$statesByPid
=
[]
Description
Each state instance SHALL reflect the current lifecycle status of a worker.
Stores all worker instances indexed by their process ID (PID).
private
array<int, Worker>
$workersByPid
=
[]
Description
Each worker instance MUST be uniquely identifiable by its PID.
Initializes the manager, validates environment support, and registers signal handlers.
public
__construct([SignalHandlerInterface
$signalHandler = new DefaultSignalHandler()][, LoggerInterface|null
$logger = null]) : mixed
Description
The implementation MUST verify that all required extensions are available. If the environment does not support forking, a RuntimeException MUST be thrown.
Parameters
Description
handler responsible for reacting to system signals
$logger
:
LoggerInterface|null
=
null
Description
logger used for lifecycle and output events
Forks one or more worker processes.
public
fork(
callable
$workerCallback[,
int
$workerCount = 1]) : WorkerGroupInterface
Description
The manager MUST NOT allow forking from within a worker process. The number of workers MUST be greater than zero.
In case of failure during creation, all previously created workers SHALL be terminated.
Parameters
$workerCallback
:
callable
Description
callback executed inside each worker process
$workerCount
:
int
=
1
Description
number of workers to spawn
Return values
Description
a group containing all created workers
Retrieves the PID of the master process.
public
getMasterPid() : int
Return values
Description
the master process identifier
Determines whether the current process is the master process.
public
isMaster() : bool
Return values
Description
true if master; otherwise false
Determines whether the current environment supports process forking.
public
isSupported() : bool
Description
All required PHP functions MUST be available for safe execution.
Return values
Description
true if forking is supported; otherwise false
Determines whether the current process is a worker process.
public
isWorker() : bool
Return values
Description
true if worker; otherwise false
Sends a signal to one or more workers.
public
kill([Signal
$signal = Signal::Terminate], WorkerInterface|WorkerGroupInterface
...$workers) : void
Description
If no workers are provided, the signal SHALL be sent to all managed workers.
Parameters
Description
signal to send (default: SIGTERM)
Description
Target workers or groups.
Waits for one or more workers or worker groups to finish execution.
public
wait(WorkerInterface|WorkerGroupInterface
...$workers) : void
Description
If no workers are provided, the manager SHALL wait for all managed workers.
Parameters
Description
Workers or groups to wait for.
Ensures that a worker belongs to this manager.
private
assertWorkerBelongsToManager(WorkerInterface
$worker) : void
Description
The method MUST reject unsupported implementations and foreign workers.
Parameters
Description
worker to validate
Collects terminated child processes.
private
collectExitedWorkers() : void
Description
The implementation MUST handle interrupted system calls and absence of child processes.
Detects the current process ID (PID).
private
detectPid() : int
Description
The implementation SHOULD prefer POSIX functions when available. If detection fails, a RuntimeException MUST be thrown.
Return values
Description
the current process identifier
Drains output buffers from all running workers.
private
drainRunningWorkerOutputs() : void
Description
This method SHOULD be called periodically to avoid blocking pipes.
Checks if any target worker is still running.
private
hasRunningTargets(
array<int, true>
$targetPids) : bool
Parameters
$targetPids
:
array<int, true>
Description
target process IDs
Return values
Description
true if at least one worker is running
Determines if a wait error was caused by an interrupted system call.
private
isInterruptedWait(
int
$error) : bool
Parameters
$error
:
int
Description
error code
Return values
Description
true if interrupted; otherwise false
Determines if there are no remaining child processes.
private
isNoChildError(
int
$error) : bool
Parameters
$error
:
int
Description
error code
Return values
Description
true if no child processes remain
Sends a signal to all provided workers.
Parameters
Registers signal handlers for all configured signals.
private
registerSignalHandlers() : void
Description
The implementation MUST enable asynchronous signal handling.
Resolves worker and group inputs into a unique set of workers.
private
resolveWorkers(WorkerInterface|WorkerGroupInterface
...$workers) : array<int, Worker>
Description
The method MUST validate ownership of each worker.
Parameters
Description
Targets to resolve.
Return values
Waits for the provided workers and processes their output streams.
private
waitOnWorkers(
array<int, Worker>
$workers) : void
Description
The method SHALL continuously monitor worker state and output until all workers terminate.
Parameters
Description
workers to monitor