# nvidia/go-gpuallocator architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia/go-gpuallocator
- Repository: https://github.com/nvidia/go-gpuallocator

## Overview

go-gpuallocator is a Go library that selects GPU devices for callers; it does not assign devices to workloads itself. Its main workflow discovers GPUs and their topology, then applies a chosen policy to select devices while tracking allocations and frees. The README also documents simple, best-effort, and static DGX policies. The graph reflects the shown allocator and device-discovery calls; unsampled policy internals are represented only where documented.

Main entry points: [`gpuallocator/allocator.go`](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/allocator.go) (Allocator state), [`gpuallocator/device.go`](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/device.go) (Device discovery), [`internal/links/device.go`](https://github.com/nvidia/go-gpuallocator/blob/main/internal/links/device.go) (Link discovery), [`gpuallocator/besteffort_policy.go`](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/besteffort_policy.go) (Best-effort policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_allocation["Allocation lifecycle"]
  node_allocator["Allocator state<br/>[allocator.go]"]
  node_discovery["Device discovery<br/>[device.go]"]
end

subgraph group_policies["Selection policies"]
  node_policy["Policy interface<br/>[allocator.go]"]
  node_simple["Simple policy<br/>[simple_policy.go]"]
  node_best["Best-effort policy"]
  node_static["Static DGX policies"]
end

subgraph group_topology["GPU topology"]
  node_device["GPU device model<br/>[device.go]"]
  node_links["Link discovery<br/>[device.go]"]
  node_pci["PCI information<br/>[pciinfo.go]"]
end

node_caller(("Library caller"))
node_nvml["NVML and device APIs"]

node_caller -->|"creates and requests"| node_allocator
node_allocator -->|"enumerates GPUs"| node_discovery
node_discovery -->|"initializes and queries"| node_nvml
node_discovery -->|"builds devices"| node_device
node_discovery -->|"queries topology"| node_links
node_device -->|"formats PCI data"| node_pci
node_links -->|"uses PCI data"| node_pci
node_allocator -->|"dispatches selection"| node_policy
node_simple -->|"implements"| node_policy
node_best -->|"implements"| node_policy
node_static -->|"implements"| node_policy
node_best -->|"scores topology"| node_links
node_allocator -->|"tracks allocate and free"| node_allocator

click node_allocator "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/allocator.go"
click node_discovery "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/device.go"
click node_device "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/device.go"
click node_policy "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/allocator.go"
click node_simple "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/simple_policy.go"
click node_best "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/besteffort_policy.go"
click node_static "https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/staticdgx_policies.go"
click node_links "https://github.com/nvidia/go-gpuallocator/blob/main/internal/links/device.go"
click node_pci "https://github.com/nvidia/go-gpuallocator/blob/main/internal/links/pciinfo.go"

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_allocator,node_discovery toneBlue
class node_policy,node_simple,node_best,node_static toneAmber
class node_device,node_links,node_pci,node_nvml toneMint
class node_caller toneIndigo
```

## Components

### Allocation lifecycle

- [Allocator state](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/allocator.go): `gpuallocator/allocator.go`
- [Device discovery](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/device.go): `gpuallocator/device.go`

### Selection policies

- [Policy interface](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/allocator.go): `gpuallocator/allocator.go`
- [Simple policy](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/simple_policy.go): `gpuallocator/simple_policy.go`
- [Best-effort policy](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/besteffort_policy.go): `gpuallocator/besteffort_policy.go`
- [Static DGX policies](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/staticdgx_policies.go): `gpuallocator/staticdgx_policies.go`

### GPU topology

- [GPU device model](https://github.com/nvidia/go-gpuallocator/blob/main/gpuallocator/device.go): `gpuallocator/device.go`
- [Link discovery](https://github.com/nvidia/go-gpuallocator/blob/main/internal/links/device.go): `internal/links/device.go`
- [PCI information](https://github.com/nvidia/go-gpuallocator/blob/main/internal/links/pciinfo.go): `internal/links/pciinfo.go`

### Other components

- **Library caller**
- **NVML and device APIs**

## Connections

- Library caller → Allocator state: creates and requests (evidence: `README.md`)
- Allocator state → Device discovery: enumerates GPUs (evidence: `gpuallocator/allocator.go`)
- Device discovery → NVML and device APIs: initializes and queries (evidence: `gpuallocator/device.go`)
- Device discovery → GPU device model: builds devices (evidence: `gpuallocator/device.go`)
- Device discovery → Link discovery: queries topology (evidence: `gpuallocator/device.go`)
- GPU device model → PCI information: formats PCI data (evidence: `gpuallocator/device.go`)
- Link discovery → PCI information: uses PCI data (evidence: `internal/links/device.go`)
- Allocator state → Policy interface: dispatches selection (evidence: `gpuallocator/allocator.go`)
- Simple policy → Policy interface: implements (evidence: `README.md`)
- Best-effort policy → Policy interface: implements (evidence: `README.md`)
- Static DGX policies → Policy interface: implements (evidence: `README.md`)
- Best-effort policy → Link discovery: scores topology (evidence: `gpuallocator/besteffort_policy.go`)
- Allocator state → Allocator state: tracks allocate and free (evidence: `gpuallocator/allocator.go`)
