# openucx/ucx architecture

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

- Interactive diagram: https://gitdiagram.com/openucx/ucx
- Repository: https://github.com/openucx/ucx

## Overview

UCX is a high-performance communication framework that presents abstract communication operations and selects available transport and hardware capabilities beneath them. Its principal workflow is an application using UCP to establish workers and endpoints, negotiate communication, and perform messaging or memory operations over UCT transports. The README documents UCP, UCT, UCS, and UCM roles and supported transport families; source excerpts are limited, so most cross-layer links below cite that documentation rather than implying inspected call paths.

Main entry points: [`src/ucp/api/ucp.h`](https://github.com/openucx/ucx/blob/master/src/ucp/api/ucp.h) (UCP API), [`src/ucp/core/ucp_ep.c`](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_ep.c) (Endpoints), [`src/uct/api/uct.h`](https://github.com/openucx/ucx/blob/master/src/uct/api/uct.h) (UCT primitives), [`src/ucp/proto/proto_select.c`](https://github.com/openucx/ucx/blob/master/src/ucp/proto/proto_select.c) (Protocol selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ucp["Protocol layer"]
  node_ucp_api["UCP API<br/>[ucp.h]"]
  node_context["Context setup<br/>[ucp_context.c]"]
  node_worker["Worker progress<br/>[ucp_worker.c]"]
  node_endpoint["Endpoints<br/>[ucp_ep.c]"]
  node_wireup["Connection wireup<br/>[wireup.c]"]
  node_tag["Tag matching<br/>[tag_send.c]"]
  node_stream["Streams<br/>[stream_send.c]"]
  node_active_message["Active messages<br/>[ucp_am.c]"]
  node_rma["RMA and atomics<br/>[rma_send.c]"]
  node_protocol["Protocol selection<br/>[proto_select.c]"]
  node_datatype["Datatype handling<br/>[dt.c]"]
  node_memory["Memory types<br/>[ucp_mm.c]"]
end

subgraph group_uct["Transport layer"]
  node_uct_api["UCT primitives<br/>[uct.h]"]
  node_network["Network transports<br/>[ib_iface.c]"]
  node_shared_memory["Shared memory<br/>[sm_iface.c]"]
  node_gpu_transports["GPU transports<br/>[cuda_copy_iface.c]"]
end

subgraph group_ucs["Common services"]
  node_ucs_services["Utilities and data structures<br/>[init.c]"]
end

subgraph group_ucm["Memory hooks"]
  node_ucm_hooks["Memory event hooks<br/>[malloc_hook.c]"]
end

node_application(("Application"))
node_perf_tool["Performance tests<br/>[perftest.c]"]
node_peer(("Remote peer"))

node_application -->|"uses primitives"| node_ucp_api
node_ucp_api -->|"initializes"| node_context
node_context -.->|"creates workers"| node_worker
node_worker -.->|"manages endpoints"| node_endpoint
node_endpoint -->|"negotiates connection"| node_wireup
node_application -->|"requests messaging"| node_tag
node_application -->|"uses streams"| node_stream
node_application -->|"uses messaging"| node_active_message
node_application -->|"requests operations"| node_rma
node_endpoint -.->|"selects protocol"| node_protocol
node_protocol -.->|"handles data"| node_datatype
node_protocol -->|"handles memory types"| node_memory
node_ucp_api -->|"uses transports"| node_uct_api
node_uct_api -->|"offers network transport"| node_network
node_uct_api -->|"offers local transport"| node_shared_memory
node_uct_api -->|"supports GPU transfers"| node_gpu_transports
node_ucp_api -.->|"uses common services"| node_ucs_services
node_ucm_hooks -->|"tracks allocation events"| node_memory
node_application -->|"runs benchmarks"| node_perf_tool
node_endpoint -.->|"communicates with"| node_peer

click node_ucp_api "https://github.com/openucx/ucx/blob/master/src/ucp/api/ucp.h"
click node_context "https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_context.c"
click node_worker "https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_worker.c"
click node_endpoint "https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_ep.c"
click node_wireup "https://github.com/openucx/ucx/blob/master/src/ucp/wireup/wireup.c"
click node_tag "https://github.com/openucx/ucx/blob/master/src/ucp/tag/tag_send.c"
click node_stream "https://github.com/openucx/ucx/blob/master/src/ucp/stream/stream_send.c"
click node_active_message "https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_am.c"
click node_rma "https://github.com/openucx/ucx/blob/master/src/ucp/rma/rma_send.c"
click node_protocol "https://github.com/openucx/ucx/blob/master/src/ucp/proto/proto_select.c"
click node_datatype "https://github.com/openucx/ucx/blob/master/src/ucp/dt/dt.c"
click node_memory "https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_mm.c"
click node_uct_api "https://github.com/openucx/ucx/blob/master/src/uct/api/uct.h"
click node_network "https://github.com/openucx/ucx/blob/master/src/uct/ib/base/ib_iface.c"
click node_shared_memory "https://github.com/openucx/ucx/blob/master/src/uct/sm/base/sm_iface.c"
click node_gpu_transports "https://github.com/openucx/ucx/blob/master/src/uct/cuda/cuda_copy/cuda_copy_iface.c"
click node_ucs_services "https://github.com/openucx/ucx/blob/master/src/ucs/sys/init.c"
click node_ucm_hooks "https://github.com/openucx/ucx/blob/master/src/ucm/malloc/malloc_hook.c"
click node_perf_tool "https://github.com/openucx/ucx/blob/master/src/tools/perf/perftest.c"

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_ucp_api,node_context,node_worker,node_endpoint,node_wireup,node_tag,node_stream,node_active_message,node_rma,node_protocol,node_datatype,node_memory toneBlue
class node_uct_api,node_network,node_shared_memory,node_gpu_transports toneAmber
class node_ucs_services toneMint
class node_ucm_hooks toneRose
class node_application,node_peer toneIndigo
class node_perf_tool toneTeal
```

## Components

### Protocol layer

- [UCP API](https://github.com/openucx/ucx/blob/master/src/ucp/api/ucp.h): `src/ucp/api/ucp.h`
- [Context setup](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_context.c): `src/ucp/core/ucp_context.c`
- [Worker progress](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_worker.c): `src/ucp/core/ucp_worker.c`
- [Endpoints](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_ep.c): `src/ucp/core/ucp_ep.c`
- [Connection wireup](https://github.com/openucx/ucx/blob/master/src/ucp/wireup/wireup.c): `src/ucp/wireup/wireup.c`
- [Tag matching](https://github.com/openucx/ucx/blob/master/src/ucp/tag/tag_send.c): `src/ucp/tag/tag_send.c`
- [Streams](https://github.com/openucx/ucx/blob/master/src/ucp/stream/stream_send.c): `src/ucp/stream/stream_send.c`
- [Active messages](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_am.c): `src/ucp/core/ucp_am.c`
- [RMA and atomics](https://github.com/openucx/ucx/blob/master/src/ucp/rma/rma_send.c): `src/ucp/rma/rma_send.c`
- [Protocol selection](https://github.com/openucx/ucx/blob/master/src/ucp/proto/proto_select.c): `src/ucp/proto/proto_select.c`
- [Datatype handling](https://github.com/openucx/ucx/blob/master/src/ucp/dt/dt.c): `src/ucp/dt/dt.c`
- [Memory types](https://github.com/openucx/ucx/blob/master/src/ucp/core/ucp_mm.c): `src/ucp/core/ucp_mm.c`

### Transport layer

- [UCT primitives](https://github.com/openucx/ucx/blob/master/src/uct/api/uct.h): `src/uct/api/uct.h`
- [Network transports](https://github.com/openucx/ucx/blob/master/src/uct/ib/base/ib_iface.c): `src/uct/ib/base/ib_iface.c`
- [Shared memory](https://github.com/openucx/ucx/blob/master/src/uct/sm/base/sm_iface.c): `src/uct/sm/base/sm_iface.c`
- [GPU transports](https://github.com/openucx/ucx/blob/master/src/uct/cuda/cuda_copy/cuda_copy_iface.c): `src/uct/cuda/cuda_copy/cuda_copy_iface.c`

### Common services

- [Utilities and data structures](https://github.com/openucx/ucx/blob/master/src/ucs/sys/init.c): `src/ucs/sys/init.c`

### Memory hooks

- [Memory event hooks](https://github.com/openucx/ucx/blob/master/src/ucm/malloc/malloc_hook.c): `src/ucm/malloc/malloc_hook.c`

### Other components

- **Application**
- [Performance tests](https://github.com/openucx/ucx/blob/master/src/tools/perf/perftest.c): `src/tools/perf/perftest.c`
- **Remote peer**

## Connections

- Application → UCP API: uses primitives (evidence: `README.md`)
- UCP API → Context setup: initializes (evidence: `README.md`)
- Context setup → Worker progress: creates workers
- Worker progress → Endpoints: manages endpoints
- Endpoints → Connection wireup: negotiates connection (evidence: `README.md`)
- Application → Tag matching: requests messaging (evidence: `README.md`)
- Application → Streams: uses streams (evidence: `README.md`)
- Application → Active messages: uses messaging (evidence: `README.md`)
- Application → RMA and atomics: requests operations (evidence: `README.md`)
- Endpoints → Protocol selection: selects protocol
- Protocol selection → Datatype handling: handles data
- Protocol selection → Memory types: handles memory types (evidence: `README.md`)
- UCP API → UCT primitives: uses transports (evidence: `README.md`)
- UCT primitives → Network transports: offers network transport (evidence: `README.md`)
- UCT primitives → Shared memory: offers local transport (evidence: `README.md`)
- UCT primitives → GPU transports: supports GPU transfers (evidence: `README.md`)
- UCP API → Utilities and data structures: uses common services
- Memory event hooks → Memory types: tracks allocation events (evidence: `README.md`)
- Application → Performance tests: runs benchmarks (evidence: `README.md`)
- Endpoints → Remote peer: communicates with
