WorkerPool

in package

• ZealPHP

Master-side pool manager for ZealPHP's native FCGI-style worker pool.

Table of Contents

Properties

$channelPopulated  : bool

true after the sync idle queue has been migrated into $idleChan on the first coroutine dispatch.

$closed  : bool

true after close() has been called; prevents double-close and guards dispatch().

$idleChan  : Channel|null

Coroutine idle queue. Created lazily — Channel push REQUIRES coroutine context, so we can't populate it at constructor time (parent worker boot is typically non-coroutine). First dispatch in a coroutine transfers the sync queue into the channel; from then on, all idle/busy transitions go through the channel for proper parallel-dispatch yield.

$idleSync  : array<int, int>

$maxRequestsPerWorker  : int

$size  : int

Total number of worker slots allocated at construction (immutable after __construct()).

$workerEntry  : string|null

$workers  : array<int, array{proc: resource, stdin: resource, stdout: resource, stderr: resource, fd3: resource|null, pid: int, served: int}>

FD-3 IPC architecture (v0.3.x): the subprocess writes the response BODY to STDOUT freely (no length-prefixed framing → no risk of corruption from user code that calls flush() / fastcgi_finish_request()) and writes the response METADATA frame (status, headers, cookies) to fd 3.

Methods

__construct()  : mixed

Spawn $size worker subprocesses immediately. All workers are ready (READY signal received) before the constructor returns.

__destruct()  : mixed

close()  : void

Shut down all workers cleanly (close pipes, wait for exit).

dispatch()  : array<string, mixed>

Dispatch one request to an idle worker and return the response frame.

filterSubprocessEnv()  : array<string, string>

Build the environment handed to a pool subprocess.

servedCounts()  : array<int, int>

Per-worker served counter (for tests / observability / /healthz).

size()  : int

How many workers are alive right now.

ensureChannelPopulated()  : void

One-time promotion of the sync idle queue into a Coroutine\Channel.

isAlive()  : bool

popIdleWorker()  : int|null

Pop an idle worker index. In a coroutine, lazy-promotes the queue to a Coroutine\Channel (first call) and yields on it until a worker is freed or the timeout expires. Outside a coroutine, uses the synchronous LIFO — no yield, returns null if empty.

readBody()  : string

Read exactly $n body bytes from STDOUT. The subprocess wrote body_length = $n into the fd 3 metadata frame and immediately after streamed $n bytes to STDOUT. Hard-capped at IPC::MAX_FRAME_BYTES (64 MB) to match the framing channel — anything bigger is a corrupted length signal.

respawn()  : void

Close all pipes for the worker at $idx, reap the subprocess via proc_close(), spawn a fresh replacement, and immediately return it to the idle pool. Called when a worker dies mid-request, hits its $maxRequestsPerWorker limit, or sends the _exit flag in its IPC frame.

returnToIdle()  : void

Return a worker to the idle pool. Routes to the channel (in coroutine context, once promoted) so any coroutine waiting on pop wakes up; otherwise pushes to the sync LIFO.

spawn()  : array{proc: resource, stdin: resource, stdout: resource, stderr: resource, fd3: resource|null, pid: int, served: int}