# frangarcj/vita-pthread-ng architecture

> Architecture diagram of the GitHub repository frangarcj/vita-pthread-ng, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frangarcj/vita-pthread-ng
- Repository: https://github.com/frangarcj/vita-pthread-ng

## Overview

vpthread-ng is a C pthread implementation for Vita, with a POSIX-compatible API and selectable Vita or Linux simulation backends. The main workflow is an application calling the POSIX shim, which delegates thread and synchronization operations to the core runtime; the runtime uses a HAL for kernel-thread and primitive operations. The core also provides cancellation, thread-specific data, cleanup, and synchronization features. Source excerpts establish several key links, but do not expose every POSIX dispatch or backend configuration detail, so uncertain connections are omitted.

Main entry points: [`src/internal.h`](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/internal.h) (Runtime State), [`src/posix.c`](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/posix.c) (POSIX Shim), [`include/vpthread/hal.h`](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal.h) (HAL Selector), [`src/thread.c`](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/thread.c) (Thread Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public APIs"]
  node_posix["POSIX Shim<br/>[posix.c]"]
  node_abi["pthread ABI<br/>[pthread.h]"]
  node_api_header["Core API<br/>[vpthread.h]"]
end

subgraph group_runtime["Thread Runtime"]
  node_thread["Thread Lifecycle<br/>[thread.c]"]
  node_cancel["Cancellation<br/>[cancel.c]"]
  node_tsd["Thread-Specific Data<br/>[tsd.c]"]
  node_internal["Runtime State<br/>[internal.h]"]
end

subgraph group_sync["Synchronization"]
  node_mutex["Mutexes<br/>[mutex.c]"]
  node_condition["Condition Variables<br/>[cond.c]"]
  node_rwlock["Read-Write Locks<br/>[rwlock.c]"]
  node_barrier["Barriers<br/>[barrier.c]"]
  node_once["Once Control<br/>[once.c]"]
end

subgraph group_hal["Platform Backends"]
  node_hal_select["HAL Selector<br/>[hal.h]"]
  node_vita_hal["Vita HAL<br/>[hal_vita.h]"]
  node_sim_hal["Simulation HAL<br/>[hal_sce_sim.h]"]
  node_sim_api["Simulation API<br/>[sce_sim.h]"]
  node_sim_runtime["Simulation Runtime<br/>[sce_sim.c]"]
end

node_application(("Application"))
node_vita_kernel(("Vita Kernel"))
node_host_threads(("Host Threads"))

node_application -->|"calls"| node_posix
node_posix -->|"implements"| node_abi
node_posix -.->|"delegates to"| node_thread
node_posix -->|"delegates to"| node_mutex
node_posix -->|"delegates to"| node_rwlock
node_thread -->|"uses state"| node_internal
node_mutex -->|"uses state"| node_internal
node_thread -->|"uses operations"| node_hal_select
node_mutex -->|"uses operations"| node_hal_select
node_condition -->|"uses state"| node_internal
node_rwlock -->|"uses state"| node_internal
node_barrier -->|"uses state"| node_internal
node_cancel -->|"uses state"| node_internal
node_tsd -->|"uses state"| node_internal
node_once -->|"uses API"| node_api_header
node_hal_select -->|"selects"| node_sim_hal
node_hal_select -->|"selects"| node_vita_hal
node_sim_hal -->|"uses API"| node_sim_api
node_sim_runtime -->|"implements"| node_sim_api
node_sim_runtime -->|"runs on"| node_host_threads
node_vita_hal -->|"calls"| node_vita_kernel

click node_posix "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/posix.c"
click node_abi "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/abi/pthread.h"
click node_api_header "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/vpthread.h"
click node_thread "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/thread.c"
click node_cancel "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/cancel.c"
click node_tsd "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/tsd.c"
click node_internal "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/internal.h"
click node_mutex "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/mutex.c"
click node_condition "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/cond.c"
click node_rwlock "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/rwlock.c"
click node_barrier "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/barrier.c"
click node_once "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/once.c"
click node_hal_select "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal.h"
click node_vita_hal "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal_vita.h"
click node_sim_hal "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal_sce_sim.h"
click node_sim_api "https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/sce_sim.h"
click node_sim_runtime "https://github.com/frangarcj/vita-pthread-ng/blob/main/src/sce_sim/sce_sim.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_posix,node_abi,node_api_header toneBlue
class node_thread,node_cancel,node_tsd,node_internal toneAmber
class node_mutex,node_condition,node_rwlock,node_barrier,node_once toneMint
class node_hal_select,node_vita_hal,node_sim_hal,node_sim_api,node_sim_runtime toneRose
class node_application,node_vita_kernel,node_host_threads toneIndigo
```

## Components

### Public APIs

- [POSIX Shim](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/posix.c): `src/posix.c`
- [pthread ABI](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/abi/pthread.h): `include/vpthread/abi/pthread.h`
- [Core API](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/vpthread.h): `include/vpthread/vpthread.h`

### Thread Runtime

- [Thread Lifecycle](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/thread.c): `src/thread.c`
- [Cancellation](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/cancel.c): `src/cancel.c`
- [Thread-Specific Data](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/tsd.c): `src/tsd.c`
- [Runtime State](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/internal.h): `src/internal.h`

### Synchronization

- [Mutexes](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/mutex.c): `src/mutex.c`
- [Condition Variables](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/cond.c): `src/cond.c`
- [Read-Write Locks](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/rwlock.c): `src/rwlock.c`
- [Barriers](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/barrier.c): `src/barrier.c`
- [Once Control](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/once.c): `src/once.c`

### Platform Backends

- [HAL Selector](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal.h): `include/vpthread/hal.h`
- [Vita HAL](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal_vita.h): `include/vpthread/hal_vita.h`
- [Simulation HAL](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/hal_sce_sim.h): `include/vpthread/hal_sce_sim.h`
- [Simulation API](https://github.com/frangarcj/vita-pthread-ng/blob/main/include/vpthread/sce_sim.h): `include/vpthread/sce_sim.h`
- [Simulation Runtime](https://github.com/frangarcj/vita-pthread-ng/blob/main/src/sce_sim/sce_sim.c): `src/sce_sim/sce_sim.c`

### Other components

- **Application**
- **Vita Kernel**
- **Host Threads**

## Connections

- Application → POSIX Shim: calls
- POSIX Shim → pthread ABI: implements (evidence: `src/posix.c`)
- POSIX Shim → Thread Lifecycle: delegates to
- POSIX Shim → Mutexes: delegates to (evidence: `src/posix.c`)
- POSIX Shim → Read-Write Locks: delegates to (evidence: `src/posix.c`)
- Thread Lifecycle → Runtime State: uses state (evidence: `src/thread.c`)
- Mutexes → Runtime State: uses state (evidence: `src/mutex.c`)
- Thread Lifecycle → HAL Selector: uses operations
- Mutexes → HAL Selector: uses operations
- Condition Variables → Runtime State: uses state (evidence: `src/cond.c`)
- Read-Write Locks → Runtime State: uses state (evidence: `src/rwlock.c`)
- Barriers → Runtime State: uses state (evidence: `src/barrier.c`)
- Cancellation → Runtime State: uses state (evidence: `src/cancel.c`)
- Thread-Specific Data → Runtime State: uses state (evidence: `src/tsd.c`)
- Once Control → Core API: uses API (evidence: `src/once.c`)
- HAL Selector → Simulation HAL: selects (evidence: `include/vpthread/hal.h`)
- HAL Selector → Vita HAL: selects (evidence: `include/vpthread/hal.h`)
- Simulation HAL → Simulation API: uses API (evidence: `include/vpthread/hal_sce_sim.h`)
- Simulation Runtime → Simulation API: implements (evidence: `src/sce_sim/sce_sim.c`)
- Simulation Runtime → Host Threads: runs on (evidence: `src/sce_sim/sce_sim.c`)
- Vita HAL → Vita Kernel: calls (evidence: `include/vpthread/hal_vita.h`)