# lauraginer/philosophers architecture

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

- Interactive diagram: https://gitdiagram.com/lauraginer/philosophers
- Repository: https://github.com/lauraginer/philosophers

## Overview

##### Project Type and Purpose
- This is a single‐process, multi‐threaded C application that simulates the Dining Philosophers problem.
- Its main goal is to demonstrate thread synchronization, deadlock prevention, precise timing, and safe resource sharing via mutexes.

##### File Structure Analysis
- Top‐level:
- Makefile – build and debug targets
- inc/philosopher.h – all shared typedefs and function prototypes
- src/ – six modules:
◦ main.c – argument parsing, initialization, thread creation
◦ utils.c – time measurement and conversion utilities
◦ mutex.c – wrapper around pthread_mutex operations
◦ threads.c – philosopher thread routines and teardown
◦ actions.c – philosopher actions (think, eat, sleep)
◦ monitor.c – separate monitor thread for detecting deaths
- Pattern: clear separation of concerns—initialization, utilities, synchronization, threading logic, monitoring.

##### Key Architectural Components
- Main Controller
- Parses arguments, allocates t_data and philosopher structures, initializes all mutexes and forks array.
- Spawns N philosopher threads + 1 monitor thread.
- Philosopher Threads (N instances)
- Loop: think → pick up forks (mutex lock) → eat → release forks (mutex unlock) → sleep
- Report actions via a thread‐safe logger mutex.
- Monitor Thread
- Periodically scans each philosopher’s last_meal timestamp under eat_mutex.
- If starvation time exceeded, sets a global death flag under dead_mutex and logs death.
- Shared Data (t_data)
- forks: array of N pthread_mutex_t
- dead_mutex, eat_mutex, log_mutex – protect global death flag, meal counters, and console output
- Configuration parameters and initial timestamp

##### Interactions and Data Flow
- Philosopher threads ↔ forks[] via fork‐mutex locks/unlocks
- Philosopher threads → shared last_meal & meal_count under eat_mutex
- All threads → log output under log_mutex
- Monitor thread reads last_meal & writes death flag under respective mutexes
- Main thread waits for termination and cleans up resources

##### Architectural Patterns and Principles
- Resource locking via pthread mutexes to avoid race conditions
- Asymmetric fork picking (odd/even ordering) to break circular wait → deadlock prevention
- Busy‐wait sleep (usleep+loop) for sub‐millisecond precision
- Single responsibility modules: easy to locate and extend functionality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Controller
    Main["Main Controller"]:::control
    click Main "https://github.com/lauraginer/philosophers/blob/main/philo/src/main.c"

    %% Utility Modules
    Utils["Utils (time measurement & busy-wait)"]:::utility
    click Utils "https://github.com/lauraginer/philosophers/blob/main/philo/src/utils.c"
    Mutex["Mutex Wrappers (forks, dead_mutex, eat_mutex, log_mutex)"]:::utility
    click Mutex "https://github.com/lauraginer/philosophers/blob/main/philo/src/mutex.c"
    Actions["Philosopher Actions (think/eat/sleep)"]:::utility
    click Actions "https://github.com/lauraginer/philosophers/blob/main/philo/src/actions.c"

    %% Threads
    subgraph "Philosopher Threads" 
        direction TB
        P1["Philosopher Thread 1"]:::philo
        Pn["Philosopher Thread N"]:::philo
    end
    click P1 "https://github.com/lauraginer/philosophers/blob/main/philo/src/threads.c"
    click Pn "https://github.com/lauraginer/philosophers/blob/main/philo/src/threads.c"

    Monitor["Monitor Thread"]:::monitor
    click Monitor "https://github.com/lauraginer/philosophers/blob/main/philo/src/monitor.c"

    %% Shared Data
    Shared["Shared Data\n(forks[N], last_meal[], meal_count[], dead_flag)"]:::data
    click Shared "https://github.com/lauraginer/philosophers/blob/main/philo/inc/philosopher.h"

    %% Logger and Build
    Logger["Console Logger"]:::data
    Makefile["Makefile (build & debug targets)"]:::utility
    click Makefile "https://github.com/lauraginer/philosophers/tree/main/philo/Makefile"

    %% Control Flow
    Main -->|"spawn threads"| P1
    Main -->|"spawn threads"| Pn
    Main -->|"spawn monitor"| Monitor
    P1 -->|"join/terminate"| Main
    Pn -->|"join/terminate"| Main
    Monitor -->|"join/terminate"| Main

    %% Thread Interactions with Shared Data
    P1 -->|"lock forks[i]"| Shared
    P1 -->|"unlock forks[i]"| Shared
    Pn -->|"lock forks[i]"| Shared
    Pn -->|"unlock forks[i]"| Shared
    P1 -->|"write last_meal"| Shared
    Pn -->|"write last_meal"| Shared
    Monitor -->|"read last_meal"| Shared
    Monitor -->|"write dead_flag"| Shared

    %% Logging
    P1 -->|"log action"| Logger
    Pn -->|"log action"| Logger
    Monitor -->|"log death"| Logger

    %% Use of utilities
    P1 -->|"use time utils"| Utils
    Pn -->|"use time utils"| Utils
    Monitor -->|"use time utils"| Utils
    P1 -->|"use mutex ops"| Mutex
    Pn -->|"use mutex ops"| Mutex
    Monitor -->|"use mutex ops"| Mutex
    P1 -->|"invoke actions"| Actions
    Pn -->|"invoke actions"| Actions

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Philosopher Thread"]:::philo
        L2["Monitor Thread"]:::monitor
        L3["Shared Data Store"]:::data
        L4["Utility Module"]:::utility
        L5["Control Flow"]:::control
    end

    classDef philo fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef monitor fill:#F08080,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef control fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef utility fill:#FFFACD,stroke:#000,stroke-width:1px
```
