# simonbrunel/qtpromise architecture

> Architecture diagram of the GitHub repository simonbrunel/qtpromise, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonbrunel/qtpromise
- Repository: https://github.com/simonbrunel/qtpromise

## Overview

QtPromise is a header-oriented Promises/A+ implementation for Qt/C++. A caller creates or adapts asynchronous work into a promise, which settles with a value or error; continuations and collection helpers transform or combine results. Qt signal and QFuture adapters bridge Qt asynchronous APIs, while event-loop dispatch and shared promise state support delivery across threads. The README also documents timeout/delay, conversion and thread safety. Some implementations are unsampled, so links to those capabilities are omitted where wiring is uncertain.

Main entry points: [`src/qtpromise/qpromiseresolver.h`](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseresolver.h) (Promise resolver), [`src/qtpromise/qpromise.inl`](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.inl) (Continuation chain), [`src/qtpromise/qpromise.h`](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.h) (QPromise API), [`src/qtpromise/qpromise_p.h`](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise_p.h) (Promise state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_promise["Promise lifecycle"]
  node_promise_api["QPromise API<br/>[qpromise.h]"]
  node_resolver["Promise resolver<br/>[qpromiseresolver.h]"]
  node_state["Promise state<br/>[qpromise_p.h]"]
end

subgraph group_composition["Composition APIs"]
  node_chain["Continuation chain<br/>[qpromise.inl]"]
  node_helpers["Collection helpers<br/>[qpromisehelpers.h]"]
  node_helper_impl["Helper internals"]
end

subgraph group_adapters["Qt adapters"]
  node_connections["Signal connections"]
  node_future_adapter["QFuture adapter<br/>[qpromisefuture.h]"]
end

subgraph group_runtime["Dispatch and errors"]
  node_exceptions["Promise exceptions"]
  node_type_traits["Callback traits<br/>[qpromiseglobal.h]"]
end

node_caller(("Library caller"))
node_qt_core["Qt Core"]
node_event_loop["Qt event loop"]

node_caller -->|"creates or chains"| node_promise_api
node_promise_api -->|"constructs resolver"| node_resolver
node_resolver -->|"settles and dispatches"| node_state
node_state -->|"notifies handlers"| node_chain
node_chain -->|"resolves next"| node_resolver
node_promise_api -->|"offers combinators"| node_helpers
node_helpers -->|"composes promises"| node_chain
node_helpers -->|"uses signal helpers"| node_helper_impl
node_helper_impl -->|"tracks connections"| node_connections
node_helper_impl -->|"connects signals"| node_qt_core
node_connections -->|"disconnects"| node_qt_core
node_caller -.->|"provides QFuture"| node_future_adapter
node_future_adapter -->|"fulfills or rejects"| node_resolver
node_state -->|"posts callbacks"| node_event_loop
node_resolver -->|"rejects with errors"| node_exceptions
node_chain -->|"deduces callbacks"| node_type_traits

click node_promise_api "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.h"
click node_resolver "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseresolver.h"
click node_state "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise_p.h"
click node_chain "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.inl"
click node_helpers "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisehelpers.h"
click node_helper_impl "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisehelpers_p.h"
click node_connections "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseconnections.h"
click node_future_adapter "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisefuture.h"
click node_exceptions "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseexceptions.h"
click node_type_traits "https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseglobal.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_promise_api,node_resolver,node_state toneBlue
class node_chain,node_helpers,node_helper_impl toneAmber
class node_connections,node_future_adapter toneMint
class node_exceptions,node_type_traits toneRose
class node_caller,node_qt_core,node_event_loop toneIndigo
```

## Components

### Promise lifecycle

- [QPromise API](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.h): `src/qtpromise/qpromise.h`
- [Promise resolver](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseresolver.h): `src/qtpromise/qpromiseresolver.h`
- [Promise state](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise_p.h): `src/qtpromise/qpromise_p.h`

### Composition APIs

- [Continuation chain](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromise.inl): `src/qtpromise/qpromise.inl`
- [Collection helpers](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisehelpers.h): `src/qtpromise/qpromisehelpers.h`
- [Helper internals](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisehelpers_p.h): `src/qtpromise/qpromisehelpers_p.h`

### Qt adapters

- [Signal connections](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseconnections.h): `src/qtpromise/qpromiseconnections.h`
- [QFuture adapter](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromisefuture.h): `src/qtpromise/qpromisefuture.h`

### Dispatch and errors

- [Promise exceptions](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseexceptions.h): `src/qtpromise/qpromiseexceptions.h`
- [Callback traits](https://github.com/simonbrunel/qtpromise/blob/master/src/qtpromise/qpromiseglobal.h): `src/qtpromise/qpromiseglobal.h`

### Other components

- **Library caller**
- **Qt Core**
- **Qt event loop**

## Connections

- Library caller → QPromise API: creates or chains
- QPromise API → Promise resolver: constructs resolver
- Promise resolver → Promise state: settles and dispatches
- Promise state → Continuation chain: notifies handlers
- Continuation chain → Promise resolver: resolves next
- QPromise API → Collection helpers: offers combinators
- Collection helpers → Continuation chain: composes promises
- Collection helpers → Helper internals: uses signal helpers
- Helper internals → Signal connections: tracks connections
- Helper internals → Qt Core: connects signals
- Signal connections → Qt Core: disconnects
- Library caller → QFuture adapter: provides QFuture
- QFuture adapter → Promise resolver: fulfills or rejects
- Promise state → Qt event loop: posts callbacks
- Promise resolver → Promise exceptions: rejects with errors
- Continuation chain → Callback traits: deduces callbacks