Represents a single forked worker process.
Description
This class encapsulates the lifecycle of a worker created via process forking. It is responsible for:
- Spawning the child process
- Executing the provided callback in the child context
- Capturing output and errors
- Synchronizing state with the master process
Instances of this class MUST be created exclusively by a manager implementation. Consumers SHOULD NOT instantiate this class directly.
Interfaces
Constants
POSIX error code for interrupted system calls.
POSIX error code for missing child processes.
POSIX error code for non-existent processes.
Properties
Stores the callback executed inside the child process.
Methods
Initializes the worker and immediately forks the process.
Returns the captured error output produced by this worker.
Returns the worker exit code when it exits normally.
Returns the captured standard output produced by this worker.
Returns the process identifier (PID) of this worker.
Returns the raw status reported by the operating system, when available.
Returns the signal that terminated the worker.
Indicates whether this worker is still running.
Sends a signal to this worker.
Waits until this worker has finished execution.
Detects the current process identifier (PID).
Executes the worker callback and normalizes the exit code.
Determines whether the current process corresponds to this worker.
Determines whether a wait failure was caused by an interrupted system call.
Determines whether no child processes remain.
Determines whether the process no longer exists.
Normalizes a callback result into a valid exit code.
Performs a non-blocking state synchronization with the worker process.
Forks the current process and initializes parent/child execution paths.
POSIX error code for interrupted system calls.
private
mixed
INTERRUPTED_SYSTEM_CALL_ERROR
=
4
POSIX error code for missing child processes.
private
mixed
NO_CHILD_PROCESS_ERROR
=
10
POSIX error code for non-existent processes.
private
mixed
NO_SUCH_PROCESS_ERROR
=
3
Stores the callback executed inside the child process.
private
callable(WorkerInterface): mixed
$callback
Description
The callback MUST accept the current worker instance as its only argument.
private
LoggerInterface|null
$logger
=
null
private
ForkManagerInterface
$manager
private
WorkerState
$state
Initializes the worker and immediately forks the process.
public
__construct(ForkManagerInterface
$manager, WorkerState
$state,
callable(WorkerInterface): mixed
$callback[, LoggerInterface|null
$logger = null]) : mixed
Description
The constructor MUST trigger process forking and configure both parent and child execution contexts accordingly.
Parameters
Description
manager responsible for this worker
$state
:
WorkerState
Description
shared mutable state between parent and child
Description
callback executed in the child process
$logger
:
LoggerInterface|null
=
null
Description
logger used for lifecycle events
Returns the captured error output produced by this worker.
public
getErrorOutput() : string
Return values
Description
the captured error output
Returns the worker exit code when it exits normally.
public
getExitCode() : int|null
Return values
Description
the exit code or null if not applicable
Returns the captured standard output produced by this worker.
public
getOutput() : string
Return values
Description
the captured output
Returns the process identifier (PID) of this worker.
public
getPid() : int
Return values
Description
the worker process identifier
Returns the raw status reported by the operating system, when available.
public
getStatus() : int|null
Return values
Description
the raw process status or null if unavailable
Returns the signal that terminated the worker.
public
getTerminationSignal() : Signal|null
Return values
Description
the terminating signal or null if not applicable
Indicates whether this worker is still running.
public
isRunning() : bool
Return values
Description
true if the worker is running; otherwise false
Sends a signal to this worker.
public
kill([Signal
$signal = Signal::Terminate]) : void
Description
This method attempts to send a POSIX signal to the worker process. If the process no longer exists, the worker SHALL be marked as detached.
Parameters
Description
the signal to send to the worker
Waits until this worker has finished execution.
public
wait() : void
Description
This method SHALL block until the worker finishes execution. It MUST NOT be invoked from within the same worker process.
Detects the current process identifier (PID).
private
detectCurrentPid() : int
Return values
Description
the current process ID
Executes the worker callback and normalizes the exit code.
private
executeCallback() : int
Description
Output buffering MUST be used to capture standard output and forward it to the parent process. Errors SHALL be intercepted and written to the worker error output channel.
Return values
Description
normalized process exit code (0–255)
Determines whether the current process corresponds to this worker.
private
isCurrentWorkerProcess() : bool
Return values
Description
true if executing inside this worker process
Determines whether a wait failure was caused by an interrupted system call.
private
isInterruptedWait(
int
$error) : bool
Parameters
$error
:
int
Description
error code returned by pcntl
Return values
Description
true if interrupted
Determines whether no child processes remain.
private
isNoChildError(
int
$error) : bool
Parameters
$error
:
int
Description
error code returned by pcntl
Return values
Description
true if no child processes exist
Determines whether the process no longer exists.
private
isNoSuchProcessError(
int
$error) : bool
Parameters
$error
:
int
Description
error code returned by POSIX APIs
Return values
Description
true if the target process is gone
Normalizes a callback result into a valid exit code.
private
normalizeExitCode(
mixed
$result) : int
Description
Integers MUST be clamped to the range 0–255. A boolean false SHALL be converted to exit code 1. Any other value SHALL result in exit code 0.
Parameters
$result
:
mixed
Description
callback return value
Return values
Description
normalized exit code
Performs a non-blocking state synchronization with the worker process.
private
pollState() : void
Description
This method MUST only operate in the master process context.
Forks the current process and initializes parent/child execution paths.
private
startForkedWorker() : void
Description
The parent process SHALL retain control and track the worker. The child process MUST execute the provided callback and terminate.