# spatie/async architecture

> Architecture diagram of the GitHub repository spatie/async, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spatie/async
- Repository: https://github.com/spatie/async

## Overview

##### Main Components
- Pool: This is the core component that manages the queue of processes/tasks, limits concurrency, and coordinates process execution (both asynchronous and synchronous modes).
- Tasks & Closures: Represented by the Task class and invokable classes. These encapsulate the work that can be run in separate processes.
- Process Components:
- ParallelProcess and SynchronousProcess in the “Process” folder show different execution modes.
- ProcessCallbacks provide hooks (then, catch, timeout) that handle outcomes of individual tasks.
- Runtime: ChildRuntime and ParentRuntime classes in the “Runtime” directory indicate the bifurcation between the main (parent) process and the spawned child processes.
- Error Handling & Output: Under the “Output” folder you see error/exception classes (e.g., ParallelError, ParallelException, SerializableException) that encapsulate how errors and outputs are communicated back to the parent process.
- Helper Functions: Found in the helper file, these provide utility functions (like async/await) that simplify managing parallel tasks.

##### Relationships and Interactions
- The Pool acts as the orchestrator. It receives tasks (as closures, invokable objects, or Task instances) and dispatches them to child processes, creating a relationship between Pool and Process components.
- Each task executed via Pool is internally wrapped by a Process (either ParallelProcess or SynchronousProcess) which handles process creation and communication.

##### Architectural Patterns and Design Principles
- The architecture follows a clear separation of concerns. The Pool coordinates and schedules tasks, while Process and Runtime components handle execution.
- The implementation uses event-driven callbacks (“then”, “catch”, “timeout”) that allow flexible handling of asynchronous events.
- There is an evident fork/signal-handling mechanism based on PHP’s PCNTL capabilities and the Symfony Process component (which is mentioned in the README).
- Although not a full-blown MVC or microservices pattern, the library’s design is modular, and each folder (Process, Output, Runtime) clearly delineates responsibility.

##### Relevant Technologies and Frameworks
- PHP’s PCNTL and POSIX extensions (for process management and signal handling)
- Symfony Process (used under the hood to manage subprocesses)
- Composer for dependency management (as seen in composer.json)
- PHPUnit (for testing, as seen in the tests directory)

##### Summarizing the System Architecture
- The developer’s interface: API for creating pools and adding tasks.
- The orchestration layer (Pool) that handles parallel processing.
- The core execution layers (Process and Runtime) that manage child processes.
- The error and output handling interface (Output classes) enabling graceful response to process results and failures.
- That all components are detailed so that one can see how asynchronous operations are managed from submission to completion.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Interface"
        Dev("Developer Code"):::developer
        Helpers("Helper Functions"):::helper
    end

    subgraph "Core Orchestration"
        Pool("Pool"):::orchestrator
        Task("Task"):::task
        FileTask("File Task"):::task
    end

    subgraph "Process Management"
        ParProc("Parallel Process"):::process
        SyncProc("Synchronous Process"):::process
        ProcCallbacks("Process Callbacks"):::callback
    end

    subgraph "Runtime Management"
        ChildRT("Child Runtime"):::runtime
        ParentRT("Parent Runtime"):::runtime
    end

    subgraph "Error and Output Handling"
        ParError("Parallel Error"):::error
        ParException("Parallel Exception"):::error
        SerializableEx("Serializable Exception"):::error
    end

    Dev -->|"calls_async/await"| Helpers
    Helpers -->|"initialize"| Pool

    Pool -->|"submit_task"| Task
    Pool -->|"submit_file_task"| FileTask

    Pool -->|"spawn_parallel"| ParProc
    Pool -->|"spawn_sync"| SyncProc

    ParProc -->|"attach_callbacks"| ProcCallbacks
    SyncProc -->|"attach_callbacks"| ProcCallbacks

    ParProc -->|"child_runtime"| ChildRT
    ChildRT -->|"notify_parent"| ParentRT
    ParentRT -->|"return_output"| Pool

    ProcCallbacks -->|"catch_error"| ParError
    ProcCallbacks -->|"throw_exception"| ParException
    ProcCallbacks -->|"serialize_error"| SerializableEx

    %% Click Events
    click Pool "https://github.com/spatie/async/blob/main/src/Pool.php"
    click Task "https://github.com/spatie/async/blob/main/src/Task.php"
    click FileTask "https://github.com/spatie/async/blob/main/src/FileTask.php"
    click ParProc "https://github.com/spatie/async/blob/main/src/Process/ParallelProcess.php"
    click SyncProc "https://github.com/spatie/async/blob/main/src/Process/SynchronousProcess.php"
    click ProcCallbacks "https://github.com/spatie/async/blob/main/src/Process/ProcessCallbacks.php"
    click ChildRT "https://github.com/spatie/async/blob/main/src/Runtime/ChildRuntime.php"
    click ParentRT "https://github.com/spatie/async/blob/main/src/Runtime/ParentRuntime.php"
    click ParError "https://github.com/spatie/async/blob/main/src/Output/ParallelError.php"
    click ParException "https://github.com/spatie/async/blob/main/src/Output/ParallelException.php"
    click SerializableEx "https://github.com/spatie/async/blob/main/src/Output/SerializableException.php"
    click Helpers "https://github.com/spatie/async/blob/main/src/helpers.php"

    %% Styles
    classDef developer fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef helper fill:#e6e6fa,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef task fill:#afeeee,stroke:#333,stroke-width:2px;
    classDef process fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef callback fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef runtime fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef error fill:#f08080,stroke:#333,stroke-width:2px;
```
