# swiftlang/swift-subprocess architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlang/swift-subprocess
- Repository: https://github.com/swiftlang/swift-subprocess

## Overview

##### Project type and purpose
- This is an open-source Swift package (“Subprocess”) that provides a cross-platform API for spawning and managing child processes.
- It is a library (not a standalone application), intended to be imported into other SwiftPM projects.

##### File structure
- Top-level artifacts:
– Package.swift, README.md, configuration files (.gitignore, CODE_OF_CONDUCT.md, etc.)
– Sources/Subprocess – the main module source tree
– Sources/_SubprocessCShims – low-level C shim code for process spawning
– Tests/SubprocessTests – unit and integration tests for each supported platform
- Sources/Subprocess subfolders:
– API.swift, Configuration.swift, Execution.swift, Error.swift – the core public API and types
– Buffer.swift, AsyncBufferSequence.swift – I/O buffering abstractions
– IO/Input.swift, IO/Output.swift – input/output option types
– Platforms/Subprocess+*.swift – platform-specific implementations (Darwin, Linux, Windows, Unix)
– SubprocessFoundation and SubprocessSpan extension folders – conditional trait additions for Foundation and RawSpan support
– Teardown.swift, Span+Subprocess.swift – process shutdown and span types

##### README for additional insights
- Describes features like run(), runDetached(), Input/Output configurations, platformOptions, customizable execution closures, and traits (SubprocessFoundation, SubprocessSpan).
- Emphasizes cross-platform parity and extension points via PlatformOptions and C shims.

a. Main components:
1) Public API Layer – exposes run(), runDetached(), types like CollectedResult, Execution, Configuration
2) I/O Abstraction Layer – Buffer, AsyncBufferSequence, Input/Output enums
3) Platform Abstraction Layer – PlatformOptions, Subprocess+Darwin/Linux/Windows/Unix
4) Native Shim Layer – _SubprocessCShims (process_shims.c, header) invoking posix_spawn/CreateProcess
5) Operating System – the underlying OS process management (macOS, Linux, Windows kernel)
6) Optional Traits – SubprocessFoundation, SubprocessSpan extension modules
b. Relationships and interactions:
– Client code calls Public API → builds a Configuration object → selects Input/Output options → supplies PlatformOptions if needed
– Public API passes control to Execution engine → I/O Abstraction Layer registers async streams or file descriptors
– Execution engine invokes the Platform Abstraction Layer (Subprocess+Platform) → which calls into the C shim layer
– Shim layer performs the actual spawn syscall / CreateProcess → OS kernel creates the child process
– OS returns process handles / PIDs → shim returns to Execution engine → Execution monitors, collects data via I/O abstractions → returns CollectedResult to client
– Traits modules plug in at compile time to extend types (Data support via Foundation, RawSpan via SwiftSpan)
c. Architectural patterns and principles:
– Layered architecture separating API, I/O, platform-specific code, and OS interface
– Dependency inversion via protocols (OutputProtocol, InputProtocol) and enums to allow easy extension
– Conditional compilation for cross-platform and trait-based features
– Asynchronous concurrency (AsyncSequence) for streaming output
d. Key technologies and libraries:
– Swift concurrency (async/await, AsyncSequence)
– SwiftPM for package management and traits
– C shim layer using posix_spawn and Windows process APIs
– Foundation (conditionally) for Data types and encodings

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client Code"]:::client

    %% Public API Layer
    subgraph "Public API Layer"
        API["API.swift"]:::api
        Config["Configuration.swift"]:::api
        Exec["Execution.swift"]:::api
        Error["Error.swift"]:::api
        Result["Result.swift"]:::api
    end

    %% I/O Abstraction Layer
    subgraph "I/O Abstraction Layer"
        Buffer["Buffer.swift"]:::io
        AsyncBuf["AsyncBufferSequence.swift"]:::io
        InputIO["Input.swift"]:::io
        OutputIO["Output.swift"]:::io
    end

    %% Platform Abstraction Layer
    subgraph "Platform Abstraction Layer"
        Darwin["Subprocess+Darwin.swift"]:::platform
        Linux["Subprocess+Linux.swift"]:::platform
        Unix["Subprocess+Unix.swift"]:::platform
        Windows["Subprocess+Windows.swift"]:::platform
    end

    %% Native Shim Layer
    subgraph "Native Shim Layer"
        ShimC["process_shims.c"]:::shim
        ShimH["process_shims.h"]:::shim
        TargetCond["target_conditionals.h"]:::shim
    end

    %% Operating System
    OS["OS Kernel"]:::os

    %% Optional Traits
    subgraph "Optional Traits"
        FoundationIn["Input+Foundation.swift"]:::traits
        FoundationOut["Output+Foundation.swift"]:::traits
        FoundationSpan["Span+SubprocessFoundation.swift"]:::traits
        SpanExt["Span+Subprocess.swift"]:::traits
    end

    %% Teardown & Utilities
    subgraph "Teardown & Utilities"
        Teardown["Teardown.swift"]:::util
        Atomic["Atomic.swift"]:::util
    end

    %% Connections
    Client -->|"run()/runDetached()"| API
    API -->|"uses Configuration"| Config
    API -->|"calls Execution"| Exec
    API -->|"returns CollectedResult"| Result
    Exec -->|"register streams"| Buffer
    Exec -->|"register streams"| AsyncBuf
    Exec -->|"uses I/O types"| InputIO
    Exec -->|"uses I/O types"| OutputIO
    Exec -->|"invoke PlatformAdapter"| Darwin
    Exec -->|"invoke PlatformAdapter"| Linux
    Exec -->|"invoke PlatformAdapter"| Unix
    Exec -->|"invoke PlatformAdapter"| Windows
    Darwin -->|"calls shim"| ShimC
    Linux -->|"calls shim"| ShimC
    Unix -->|"calls shim"| ShimC
    Windows -->|"calls shim"| ShimC
    ShimC -->|"includes"| ShimH
    ShimC -->|"includes"| TargetCond
    ShimC -->|"posix_spawn/CreateProcess"| OS
    OS -->|"returns PID/handle"| ShimC
    ShimC -->|"returns to Exec"| Exec
    Exec -->|"on finish"| Teardown
    Exec -->|"atomic ops"| Atomic
    Client -.->|"imports traits"| FoundationIn
    Client -.->|"imports traits"| FoundationOut
    Client -.->|"imports traits"| FoundationSpan
    Client -.->|"imports traits"| SpanExt

    %% Click Events
    click API "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/API.swift"
    click Config "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Configuration.swift"
    click Exec "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Execution.swift"
    click Error "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Error.swift"
    click Result "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Result.swift"
    click Buffer "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Buffer.swift"
    click AsyncBuf "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/AsyncBufferSequence.swift"
    click InputIO "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/IO/Input.swift"
    click OutputIO "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/IO/Output.swift"
    click Darwin "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Platforms/Subprocess+Darwin.swift"
    click Linux "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Platforms/Subprocess+Linux.swift"
    click Unix "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Platforms/Subprocess+Unix.swift"
    click Windows "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Platforms/Subprocess+Windows.swift"
    click ShimC "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/_SubprocessCShims/process_shims.c"
    click ShimH "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/_SubprocessCShims/include/process_shims.h"
    click TargetCond "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/_SubprocessCShims/include/target_conditionals.h"
    click FoundationIn "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/SubprocessFoundation/Input+Foundation.swift"
    click FoundationOut "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/SubprocessFoundation/Output+Foundation.swift"
    click FoundationSpan "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/SubprocessFoundation/Span+SubprocessFoundation.swift"
    click SpanExt "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Span+Subprocess.swift"
    click Teardown "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Teardown.swift"
    click Atomic "https://github.com/swiftlang/swift-subprocess/blob/main/Sources/Subprocess/Atomic.swift"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef io fill:#c8e6c9,stroke:#43a047,stroke-width:1px
    classDef platform fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px
    classDef shim fill:#ffcdd2,stroke:#e53935,stroke-width:1px
    classDef os fill:#eceff1,stroke:#90a4ae,stroke-width:1px
    classDef traits fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef util fill:#d7ccc8,stroke:#5d4037,stroke-width:1px
```
