# lampepfl/gears architecture

> Architecture diagram of the GitHub repository lampepfl/gears, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lampepfl/gears
- Repository: https://github.com/lampepfl/gears

## Overview

##### Main Components

a. Core Components (from shared/src/main/scala/async):
- Async Runtime Core
- AsyncOperations
- AsyncSupport
- CompletionGroup
- Cancellable
- Resource Management System
- Concurrency Primitives
- Channels
- Semaphores
- Timers
- Future/Promise Implementation
- Listener System

b. Platform-Specific Implementations:
- JVM Implementation (jvm/)
- Virtual Thread Support
- Default JVM Support
- JVM-specific Async Operations
- Native Implementation (native/)
- ForkJoin Support
- Native-specific Async Operations

c. IO System:
- PosixLikeIO Implementation

**┌─────────────────────────────────────────┐**
- Application Layer            │
- ┤
- Cross-Platform Core Layer       │
- ┬───────────────────┐ │
- JVM Platform    │  Native Platform  │ │
- Implementation  │  Implementation   │ │
- ┴───────────────────┘ │

##### Component Relationships

- Dependencies between components
- Data flow directions
- Inheritance relationships
- Cross-platform boundaries

##### Specific Elements

a. Core Layer:
**┌─────────────────────────────────────────┐**
- Async Core                 │
- ┬───────────┬────────────────┤
- Channels  │ Futures   │   Resources    │
- ┼───────────┼────────────────┤
- Semaphores │  Timers   │   Listeners    │
- ┴───────────┴────────────────┘

b. Platform-specific implementations:
**┌─────────────────┐    ┌─────────────────┐**
- JVM Platform   │    │ Native Platform  │
- ┤    ├─────────────────┤
- VThreadSupport  │    │ ForkJoinSupport │
- DefaultSupport  │    │ DefaultSupport  │
- ┘    └─────────────────┘

##### Implementation Notes

- Use UML notation for class relationships
- Notes for important cross-cutting concerns
- Version compatibility requirements

##### Key Features to Emphasize

- Structured concurrency support
- Direct-style programming capabilities
- Cross-platform compatibility
- Resource management and cancellation
- Event handling system

Remember to include a section showing how external applications would interact with the library, demonstrating the public API surface and common usage patterns.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#b3d1ff,stroke:#333
    classDef resource fill:#90EE90,stroke:#333
    classDef platform fill:#FFB366,stroke:#333
    classDef io fill:#DDA0DD,stroke:#333
    classDef support fill:#D3D3D3,stroke:#333
    classDef api fill:#E6E6FA,stroke:#333

    %% Application Layer
    subgraph AppLayer["Application Layer"]
        UserApp["User Application Code"]
    end

    %% Public API Layer
    subgraph APILayer["Gears Public API Layer"]
        AsyncOps["Async Operations"]:::api
        Channels["Channel System"]:::api
        Resources["Resource Management"]:::api
        Scheduling["Scheduling"]:::api
    end

    %% Core Implementation Layer
    subgraph CoreLayer["Core Implementation Layer"]
        AsyncRuntime["Async Runtime Core"]:::core
        ChannelImpl["Channel Implementation"]:::core
        ResourceMgmt["Resource Manager"]:::core
        Timer["Timer System"]:::core
        Semaphore["Semaphore"]:::support
        ErrorHandling["Error Handling & Retry"]:::support
        Listener["Listener System"]:::support
        Cancel["Cancellation Support"]:::support
        CompGroup["Completion Groups"]:::support
        FutureInteg["Future Integration"]:::support
    end

    %% Platform Implementation Layer
    subgraph PlatformLayer["Platform Implementation Layer"]
        JVMImpl["JVM Implementation"]:::platform
        NativeImpl["Native Implementation"]:::platform
        POSIX["POSIX-like IO"]:::io
    end

    %% Relationships
    UserApp --> AsyncOps
    UserApp --> Channels
    UserApp --> Resources
    UserApp --> Scheduling

    AsyncOps --> AsyncRuntime
    Channels --> ChannelImpl
    Resources --> ResourceMgmt
    Scheduling --> Timer

    AsyncRuntime --> JVMImpl
    AsyncRuntime --> NativeImpl
    AsyncRuntime --> Listener
    AsyncRuntime --> Cancel
    AsyncRuntime --> CompGroup
    AsyncRuntime --> FutureInteg

    ChannelImpl --> Listener
    ResourceMgmt --> ErrorHandling
    Timer --> Semaphore

    JVMImpl --> POSIX
    NativeImpl --> POSIX

    %% Click Events
    click AsyncRuntime "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Async.scala"
    click ChannelImpl "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/channels.scala"
    click ResourceMgmt "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Resource.scala"
    click Timer "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Timer.scala"
    click Semaphore "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Semaphore.scala"
    click ErrorHandling "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/retry.scala"
    click JVMImpl "https://github.com/lampepfl/gears/blob/main/jvm/src/main/scala/async/JvmAsyncOperations.scala"
    click NativeImpl "https://github.com/lampepfl/gears/blob/main/native/src/main/scala/async/ForkJoinSupport.scala"
    click POSIX "https://github.com/lampepfl/gears/blob/main/jvm/src/main/scala/PosixLikeIO/PIO.scala"
    click Listener "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Listener.scala"
    click Cancel "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/Cancellable.scala"
    click CompGroup "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/CompletionGroup.scala"
    click FutureInteg "https://github.com/lampepfl/gears/blob/main/shared/src/main/scala/async/futures.scala"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Resource Components"]:::resource
        L3["Platform-Specific"]:::platform
        L4["IO Operations"]:::io
        L5["Support Utilities"]:::support
        L6["Public API"]:::api
    end
```
