# abhijeet-ist/thread_management_library architecture

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

- Interactive diagram: https://gitdiagram.com/abhijeet-ist/thread_management_library
- Repository: https://github.com/abhijeet-ist/thread_management_library

## Overview

1. **Repository shape**
   - This is a C library project, not an application server or service.
   - The main deliverable is a reusable static library, `libsthread.a`, built from `src/` and exposed through `include/sthread.h`.
   - Surrounding the library are standalone test binaries, example programs, and a benchmark.

2. **Public API boundary**
   - `include/sthread.h` is the only intended external entry point.
   - It exposes the thread-pool API plus mutex, semaphore, and condition-variable abstractions.
   - Everything under `src/` is internal implementation detail and should be treated as hidden from consumers.

3. **Core subsystem: thread pool**
   - `src/thread_pool.c/.h` is the central runtime subsystem.
   - It owns the worker threads, shutdown lifecycle, pending/active task accounting, and task submission/waiting semantics.
   - The public functions like `sthread_pool_create`, `submit`, `wait`, and `destroy` map directly onto this layer.

4. **Task scheduling and queueing**
   - `src/scheduler.c/.h` provides the task queue and scheduling logic used by the pool.
   - The design is FIFO and bounded, with backpressure when the queue reaches capacity.
   - This scheduler is the main data-flow bridge between producers calling `submit` and worker threads consuming tasks.

5. **Synchronization primitives**
   - `src/sync.c/.h` implements the library’s mutex, semaphore, and condition-variable APIs.
   - These primitives are used both by the public API and internally by the pool/queue to coordinate workers and waiters.
   - The semaphore is portable and, per the README, is implemented using mutex + condition variable rather than relying on platform-specific unnamed semaphores.

6. **Platform abstraction layer**
   - `src/platform.c/.h` isolates OS-specific behavior needed for cross-platform support on macOS and Linux.
   - It handles runtime/environment differences such as timing and thread/OS integration details.
   - This boundary is important because the same higher-level thread pool and sync APIs are meant to compile and behave consistently on both platforms.

7. **Memory management layer**
   - `src/memory.c/.h` centralizes allocation and resource-handling helpers.
   - This keeps low-level memory concerns out of the scheduler and pool logic, and makes failure handling more uniform.
   - In an architecture diagram, this is a supporting subsystem used by most internal components rather than a standalone feature.

8. **Execution flow**
   - Client code calls into the public API.
   - `sthread_pool_submit` places work into the scheduler queue.
   - Worker threads in the pool dequeue tasks, execute user-supplied callbacks, and update active/pending state.
   - `sthread_pool_wait` blocks until the queue drains and all active work finishes.
   - `sthread_pool_destroy` follows an orderly shutdown path: signal shutdown, wake workers, join threads, then free resources.

9. **Concurrency model**
   - The library is designed around a shared task queue and a fixed set of reusable workers.
   - There is no work stealing or task cancellation; workers all pull from the same queue in FIFO order.
   - Synchronization is central: mutexes protect shared state, condition variables coordinate waits/signals, and the portable semaphore abstraction supports counting and blocking behavior.

10. **Build and packaging**
   - The project uses CMake and a Makefile to produce the library and the sample/test executables.
   - The build output in `build/` includes the static library plus binaries for tests, demos, and the benchmark.
   - This reinforces that the repo is a library-first codebase with verification and demonstration programs as separate consumers.

11. **Validation and examples**
   - `tests/` contains focused validation binaries: creation, synchronization, pool behavior, and scalability.
   - `examples/` shows real usage patterns: a basic thread demo, matrix multiplication using parallelism, and a visual demo.
   - `benchmarks/bench_throughput.c` measures pool throughput and is useful for understanding performance goals of the architecture.

12. **Main architectural boundaries to diagram**
   - External consumers only see `sthread.h`.
   - Internal implementation splits into four major subsystems: pool, scheduler, sync primitives, and platform/memory support.
   - Test, example, and benchmark executables are separate leaf consumers that link against the same library rather than duplicating logic.

Main entry points: [`include/sthread.h`](https://github.com/abhijeet-ist/thread_management_library/blob/main/include/sthread.h) (sthread.h), [`src/thread_pool.c`](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/thread_pool.c) (Pool), [`src/sync.c`](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sync.c) (Sync), [`src/sthread.c`](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sthread.c) (sthread.c)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_include_sthread_h["sthread.h<br/>public API<br/>[sthread.h]"]
end

subgraph group_core["Core runtime"]
  node_src_sthread_c["sthread.c<br/>API glue<br/>[sthread.c]"]
  node_src_thread_pool_c["Pool<br/>[thread_pool.c]"]
  node_src_scheduler_c["Scheduler<br/>task queue<br/>[scheduler.c]"]
end

subgraph group_support["Support layer"]
  node_src_sync_c["Sync<br/>primitives<br/>[sync.c]"]
  node_src_platform_c["Platform<br/>os portability<br/>[platform.c]"]
  node_src_memory_c["Memory<br/>alloc helpers<br/>[memory.c]"]
end

subgraph group_consumers["Consumers"]
  node_examples_hello_threads_c["Hello demo<br/>example binary<br/>[hello_threads.c]"]
  node_examples_matrix_multiply_c["Matrix demo<br/>example binary<br/>[matrix_multiply.c]"]
  node_examples_visual_demo_c["Visual demo<br/>example binary<br/>[visual_demo.c]"]
  node_tests_test_create_c["Create test<br/>test binary<br/>[test_create.c]"]
  node_tests_test_pool_c["Pool test<br/>test binary<br/>[test_pool.c]"]
  node_tests_test_scale_c["Scale test<br/>test binary<br/>[test_scale.c]"]
  node_tests_test_sync_c["Sync test<br/>test binary<br/>[test_sync.c]"]
  node_benchmarks_bench_throughput_c["Throughput bench<br/>benchmark<br/>[bench_throughput.c]"]
end

subgraph group_build["Build"]
  node_cmake_make["Build system<br/>build tooling"]
  node_build_libsthread_a[("libsthread.a<br/>static library<br/>[libsthread.a]")]
end

node_include_sthread_h -->|"declares"| node_src_sthread_c
node_src_sthread_c -->|"creates"| node_src_thread_pool_c
node_src_sthread_c -->|"exposes"| node_src_sync_c
node_src_thread_pool_c -->|"submits to"| node_src_scheduler_c
node_src_scheduler_c -->|"feeds"| node_src_thread_pool_c
node_src_thread_pool_c -->|"coordinates with"| node_src_sync_c
node_src_thread_pool_c -->|"depends on"| node_src_platform_c
node_src_thread_pool_c -->|"allocates via"| node_src_memory_c
node_src_scheduler_c -->|"uses"| node_src_sync_c
node_src_sync_c -->|"abstracts"| node_src_platform_c
node_src_sync_c -->|"uses"| node_src_memory_c
node_src_platform_c -->|"uses"| node_src_memory_c
node_cmake_make -->|"produces"| node_build_libsthread_a
node_cmake_make -->|"builds"| node_examples_hello_threads_c
node_cmake_make -->|"builds"| node_examples_matrix_multiply_c
node_cmake_make -->|"builds"| node_examples_visual_demo_c
node_cmake_make -->|"builds"| node_tests_test_create_c
node_cmake_make -->|"builds"| node_tests_test_pool_c
node_cmake_make -->|"builds"| node_tests_test_scale_c
node_cmake_make -->|"builds"| node_tests_test_sync_c
node_cmake_make -->|"builds"| node_benchmarks_bench_throughput_c
node_examples_hello_threads_c -.->|"consumes"| node_include_sthread_h
node_examples_matrix_multiply_c -.->|"consumes"| node_include_sthread_h
node_examples_visual_demo_c -.->|"consumes"| node_include_sthread_h
node_tests_test_create_c -.->|"validates"| node_include_sthread_h
node_tests_test_pool_c -.->|"validates"| node_include_sthread_h
node_tests_test_scale_c -.->|"validates"| node_include_sthread_h
node_tests_test_sync_c -.->|"validates"| node_include_sthread_h
node_benchmarks_bench_throughput_c -.->|"measures"| node_include_sthread_h

click node_include_sthread_h "https://github.com/abhijeet-ist/thread_management_library/blob/main/include/sthread.h"
click node_src_sthread_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sthread.c"
click node_src_thread_pool_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/thread_pool.c"
click node_src_scheduler_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/scheduler.c"
click node_src_sync_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sync.c"
click node_src_platform_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/platform.c"
click node_src_memory_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/src/memory.c"
click node_examples_hello_threads_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/hello_threads.c"
click node_examples_matrix_multiply_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/matrix_multiply.c"
click node_examples_visual_demo_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/visual_demo.c"
click node_tests_test_create_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_create.c"
click node_tests_test_pool_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_pool.c"
click node_tests_test_scale_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_scale.c"
click node_tests_test_sync_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_sync.c"
click node_benchmarks_bench_throughput_c "https://github.com/abhijeet-ist/thread_management_library/blob/main/benchmarks/bench_throughput.c"
click node_build_libsthread_a "https://github.com/abhijeet-ist/thread_management_library/blob/main/build/libsthread.a"

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_include_sthread_h toneBlue
class node_src_sthread_c,node_src_thread_pool_c,node_src_scheduler_c toneAmber
class node_src_sync_c,node_src_platform_c,node_src_memory_c toneMint
class node_examples_hello_threads_c,node_examples_matrix_multiply_c,node_examples_visual_demo_c,node_tests_test_create_c,node_tests_test_pool_c,node_tests_test_scale_c,node_tests_test_sync_c,node_benchmarks_bench_throughput_c toneRose
class node_cmake_make,node_build_libsthread_a toneIndigo
```

## Components

### Public API

External surface exposed to library consumers.

- [sthread.h](https://github.com/abhijeet-ist/thread_management_library/blob/main/include/sthread.h): public API · Single external header for thread-pool and sync abstractions. · `include/sthread.h`

### Core runtime

Thread pool execution and task scheduling internals.

- [sthread.c](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sthread.c): API glue · Bridges the public API to internal subsystems. · `src/sthread.c`
- [Pool](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/thread_pool.c): thread pool · Owns workers, lifecycle, submission, waiting, and shutdown. · `src/thread_pool.c`
- [Scheduler](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/scheduler.c): task queue · Bounded FIFO queue and backpressure for submitted work. · `src/scheduler.c`

### Support layer

Portable synchronization, platform, and memory helpers.

- [Sync](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/sync.c): primitives · Mutex, semaphore, and condition-variable implementations. · `src/sync.c`
- [Platform](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/platform.c): os portability · OS-specific timing and runtime integration for Linux and macOS. · `src/platform.c`
- [Memory](https://github.com/abhijeet-ist/thread_management_library/blob/main/src/memory.c): alloc helpers · Centralized allocation and resource-handling helpers. · `src/memory.c`

### Consumers

Standalone binaries that link against the library.

- [Hello demo](https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/hello_threads.c): example binary · Basic thread usage example. · `examples/hello_threads.c`
- [Matrix demo](https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/matrix_multiply.c): example binary · Parallel matrix multiplication example. · `examples/matrix_multiply.c`
- [Visual demo](https://github.com/abhijeet-ist/thread_management_library/blob/main/examples/visual_demo.c): example binary · Interactive or visual usage demonstration. · `examples/visual_demo.c`
- [Create test](https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_create.c): test binary · Validates creation and initialization behavior. · `tests/test_create.c`
- [Pool test](https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_pool.c): test binary · Exercises pool behavior and task execution semantics. · `tests/test_pool.c`
- [Scale test](https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_scale.c): test binary · Checks scalability under larger workloads. · `tests/test_scale.c`
- [Sync test](https://github.com/abhijeet-ist/thread_management_library/blob/main/tests/test_sync.c): test binary · Validates synchronization primitives and coordination. · `tests/test_sync.c`
- [Throughput bench](https://github.com/abhijeet-ist/thread_management_library/blob/main/benchmarks/bench_throughput.c): benchmark · Measures task throughput of the pool. · `benchmarks/bench_throughput.c`

### Build

Project build and packaging entry points.

- **Build system**: build tooling · CMake and Makefile build the static library and executables.
- [libsthread.a](https://github.com/abhijeet-ist/thread_management_library/blob/main/build/libsthread.a): static library · Primary reusable library artifact produced from src/. · `build/libsthread.a`

## Connections

- sthread.h → sthread.c: declares · Public API declarations are implemented by the internal shim.
- sthread.c → Pool: creates · API entry points construct and control pool instances.
- sthread.c → Sync: exposes · Public mutex, semaphore, and condition-variable wrappers.
- Pool → Scheduler: submits to · Work enters the bounded FIFO scheduler.
- Scheduler → Pool: feeds · Workers pull queued tasks for execution.
- Pool → Sync: coordinates with · Mutexes and condition variables guard shared pool state.
- Pool → Platform: depends on · Pool runtime behavior relies on portable platform services.
- Pool → Memory: allocates via · Pool objects and resources use centralized allocation helpers.
- Scheduler → Sync: uses · Queue state and backpressure require synchronization.
- Sync → Platform: abstracts · Synchronization layer adapts to platform-specific behavior.
- Sync → Memory: uses · Primitive setup and teardown share memory helpers.
- Platform → Memory: uses · Platform support shares resource helpers.
- Build system → libsthread.a: produces · Build tooling emits the static library artifact.
- Build system → Hello demo: builds · Example binaries are linked against the library.
- Build system → Matrix demo: builds · Example binaries are linked against the library.
- Build system → Visual demo: builds · Example binaries are linked against the library.
- Build system → Create test: builds · Validation binaries link against the library.
- Build system → Pool test: builds · Validation binaries link against the library.
- Build system → Scale test: builds · Validation binaries link against the library.
- Build system → Sync test: builds · Validation binaries link against the library.
- Build system → Throughput bench: builds · Benchmark binary links against the library.
- Hello demo → sthread.h: consumes · Example uses the public library API.
- Matrix demo → sthread.h: consumes · Example uses the public library API.
- Visual demo → sthread.h: consumes · Example uses the public library API.
- Create test → sthread.h: validates · Test exercises the public API surface.
- Pool test → sthread.h: validates · Test exercises the public API surface.
- Scale test → sthread.h: validates · Test exercises the public API surface.
- Sync test → sthread.h: validates · Test exercises the public API surface.
- Throughput bench → sthread.h: measures · Benchmark drives the public API under load.