# rust-lang/futures-rs architecture

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

- Interactive diagram: https://gitdiagram.com/rust-lang/futures-rs
- Repository: https://github.com/rust-lang/futures-rs

## Overview

- futures-core – the core traits (e.g., Future, Stream) and fundamental abstractions;
- futures-channel – implementations for communication channels (mpsc, oneshot, etc.);
- futures-executor – executors to run futures (e.g., local and thread pool executors);
- futures-io – traits and utilities related to asynchronous I/O;
- futures-sink – the Sink trait and related combinators;
- futures-task – Waker and task handling logic;
- futures-macro – macros to simplify async code development (join!, select!, etc.);
- futures-util – a toolkit of useful combinators, adapters, and helper methods that build on the other components;
- futures-test – test utilities and scenarios to validate behavior; and
- examples – demonstrating the library’s different programming paradigms (functional and imperative styles).

##### Main components
a. Core Package Layer: Include the “futures-core” crate at the center since it defines the core traits (e.g., Future and Stream) and the basic abstractions needed by all other components.
b. Utility/Adapter Layer: Represent “futures-util” and “futures-macro” as components that extend the core functionality through combinators, adapters, and macros.
c. Channel and I/O Layer: Show “futures-channel”, “futures-io”, and “futures-sink” as parts that address asynchronous communication, I/O operations, and sink handling.
d. Executor/Task Management: Display “futures-executor” and “futures-task” as the execution/runtime components that manage task scheduling, waker functionality, and thread pooling.
e. Testing & Examples: Optionally include “futures-test” and the “examples” directories as part of the ecosystem that demonstrate and validate usage.

##### Relationships and interactions
– “futures-channel”, “futures-io”, and “futures-sink” might also depend on “futures-core”.
– “futures-executor” and “futures-task” are tightly coupled with “futures-core” and provide mechanisms to drive asynchronous computations.
- That the “futures” top-level crate aggregates or re-exports functionalities from all these sub-crates.

##### Architectural patterns and design principles
- Modularity: Each crate encapsulates its responsibilities. Visually separate these components for clarity.
- Zero-cost abstraction: Emphasize how the design chooses compile-time abstractions without runtime overhead.
- Separation of concerns: For instance, task scheduling is isolated in futures-executor and futures-task, while combinators and macros have their own crates.

##### Technologies and libraries
- That the project is written in Rust using Cargo for package management.
- Mention important Rust language features (traits, macros, zero-cost abstractions) that are central to this design.
- Optionally reference how “#[no_std]” support is provided by exposing a reduced API surface for bare metal environments (as highlighted in the README).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Futures Monorepo"
        aggregator["Futures (Monorepo)"]:::aggregator
    end

    subgraph "Core Package Layer"
        core["futures-core: Core traits and abstractions"]:::core
    end

    subgraph "Utility/Adapter Layer"
        util["futures-util: Combinators and adapters"]:::utility
        macro["futures-macro: Async code macros"]:::utility
    end

    subgraph "Channel and I/O Layer"
        channel["futures-channel: Communication channels"]:::io
        io_node["futures-io: Async I/O traits and utilities"]:::io
        sink["futures-sink: Sink trait and combinators"]:::io
    end

    subgraph "Executor/Task Management"
        executor["futures-executor: Executors for running futures"]:::executor
        task["futures-task: Task scheduling and waker"]:::executor
    end

    subgraph "Testing & Examples"
        test["futures-test: Test utilities"]:::test
        examples["examples: Usage demonstrations"]:::test
    end

    %% Aggregator relationship
    aggregator -->|"aggregates"| core

    %% Utility/Adapter dependencies on core
    util -->|"uses"| core
    macro -->|"uses"| core

    %% Channel and I/O dependencies on core
    channel -->|"uses"| core
    io_node -->|"uses"| core
    sink -->|"uses"| core

    %% Executor/Task Management dependencies on core and integration between them
    executor -->|"drives"| core
    task -->|"supports"| core
    executor <-->|"integrates"| task

    %% Testing & Examples dependencies on core
    test -->|"tests"| core
    examples -->|"demonstrates"| core

    %% Click Events
    click core "https://github.com/rust-lang/futures-rs/tree/master/futures-core"
    click util "https://github.com/rust-lang/futures-rs/tree/master/futures-util"
    click macro "https://github.com/rust-lang/futures-rs/tree/master/futures-macro"
    click channel "https://github.com/rust-lang/futures-rs/tree/master/futures-channel"
    click io_node "https://github.com/rust-lang/futures-rs/tree/master/futures-io"
    click sink "https://github.com/rust-lang/futures-rs/tree/master/futures-sink"
    click executor "https://github.com/rust-lang/futures-rs/tree/master/futures-executor"
    click task "https://github.com/rust-lang/futures-rs/tree/master/futures-task"
    click test "https://github.com/rust-lang/futures-rs/tree/master/futures-test"
    click examples "https://github.com/rust-lang/futures-rs/tree/master/examples"

    %% Styles
    classDef core fill:#c7f9cc,stroke:#0b8457,stroke-width:2px;
    classDef utility fill:#cdb4db,stroke:#6d6875,stroke-width:2px;
    classDef io fill:#fed8b1,stroke:#e07a5f,stroke-width:2px;
    classDef executor fill:#a1c8f7,stroke:#02457a,stroke-width:2px;
    classDef test fill:#ffcccb,stroke:#d62828,stroke-width:2px;
    classDef aggregator fill:#fef3bd,stroke:#f4a261,stroke-width:2px;
```
