Download the PHP package venndev/vosaka-fourotines without Composer

VOsaka Foroutines

A PHP library for structured asynchronous programming using foroutines (fiber + coroutines), inspired by Kotlin coroutines. This is project with the contribution of a project from php-async

📚 Documentation

New to VOsaka Foroutines? Check out our Structured Documentation (following the Diátaxis framework), which includes:

• Tutorials: Step-by-step learning lessons.
• How-to Guides: Task-oriented recipes for common problems.
• Reference: Detailed technical descriptions of the API.
• Explanation: Conceptual overviews and architectural deep-dives.

Architecture

Features

Core — RunBlocking, Launch, Async, Async::awaitAll(), Delay, Repeat, WithTimeout, Job lifecycle

Dispatchers — DEFAULT (fibers + AsyncIO), IO (child process via WorkerPool), MAIN (event loop)

WorkerPool — Pre-spawned long-lived worker processes with task batching, dynamic pool sizing, and respawn backoff

FiberPool — Reusable Fiber instances for scheduler optimization (default: 10, dynamic sizing)

Channel — Four transports: in-process, socket pool (default), socket per-channel, file-based

AsyncIO — Non-blocking stream I/O via stream_select() (TCP, TLS, HTTP, files, DNS)

Flow — Cold Flow, SharedFlow, StateFlow with backpressure (SUSPEND, DROP_OLDEST, DROP_LATEST, ERROR)

Actor Model — Message-passing concurrency with Channel-based mailboxes and ActorSystem registry

Supervisor Tree — OTP-style supervision with ONE_FOR_ONE, ONE_FOR_ALL, REST_FOR_ONE strategies

Sync — Mutex (file, semaphore, APCu), Select for channel multiplexing

Rules

Requirements

• PHP 8.2+
• ext-shmop, ext-fileinfo, ext-zlib

Installation

Usage

All entry points must be wrapped in main() or use the #[AsyncMain] attribute:

RunBlocking + Launch

Async / Await

Async::awaitAll — Concurrent Awaiting

awaitAll() drives multiple async tasks forward simultaneously, returning all results in order. This is significantly more efficient than awaiting sequentially.

WithTimeout

Job Lifecycle

Channel

Non-blocking operations:

Channels utility class:

Select

Flow

AsyncIO — Non-blocking Stream I/O

All methods return Deferred — a lazy wrapper that executes on ->await():

Mutex

Dispatchers

Thread::await()

While RunBlocking automatically drains all pending tasks before returning, Thread::await() allows you to manually block and drive the event loop until all work (Launch jobs, WorkerPool tasks, and AsyncIO) is finished.

When do you need it?

• Inside RunBlocking: If you want to ensure all background tasks (like Launch jobs) are completed before proceeding to the next line of code within the same RunBlocking block.
• Outside RunBlocking: When you are using AsyncMain or main() and have scheduled tasks that need to be completed before the script exits, but you aren't using a blocking runner.

WorkerPool

A pool of pre-spawned long-lived child processes. On Linux/macOS uses pcntl_fork() + Unix socket pairs; on Windows uses proc_open() + TCP loopback sockets.

Task Batching

When many small tasks are submitted, IPC round-trip overhead dominates. Task batching groups multiple tasks into a single message sent to each worker, dramatically reducing round-trips.

Batching is fully backward compatible — when batchSize=1, the pool uses the original TASK:/RESULT: protocol.

Dynamic Pool Sizing

The pool can automatically scale between a minimum and maximum number of workers based on workload pressure.

Scale-up: When all workers are busy and tasks are queued, a new worker is spawned (up to maxPoolSize).

Scale-down: When a worker has been idle longer than idleTimeout and the pool exceeds minPoolSize, it is shut down.

When dynamic scaling is disabled (default), the pool behaves exactly as before — a fixed number of workers.

Worker Respawn Backoff

When a worker crashes repetitively, respawning uses exponential backoff (100ms → 200ms → … max 30s) to prevent CPU spin. After 10 consecutive failures, the worker slot is removed (circuit-breaker).

FiberPool

Reusable Fiber instances to reduce allocation overhead. Integrated into Launch, Async, RunBlocking.

Actor Model

Supervisor Tree

OTP-style supervision with automatic restart on child failure.

ForkProcess

On Linux/macOS, ForkProcess creates child processes by forking the current process instead of spawning a new interpreter:

Selection is automatic — Worker uses fork when available, falls back to symfony/process on Windows.

Platform Support

Comparison with JavaScript Async

License

GNU Lesser General Public License v2.1