# m-elhouary/philosopher architecture

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

- Interactive diagram: https://gitdiagram.com/m-elhouary/philosopher
- Repository: https://github.com/m-elhouary/philosopher

## Overview

##### Main Components
- CLI & Argument Parser
- Module: parse_arg.c
- Responsibility: validate and convert command-line inputs into a shared configuration structure
- Data Initialization
- Module: initial_data.c
- Responsibility: allocate and initialize shared data (philosopher structs, forks/mutexes, flags)
- Thread Manager
- Module: creat_thread.c
- Responsibility: spawn N philosopher threads + 1 monitor thread
- Philosopher Threads
- Module: simulation.c
- Responsibility: loop through thinking → eating → sleeping
- Monitor Thread
- Module: monitor.c
- Responsibility: periodically check last-meal timestamps, detect death or completion
- Shared Resources & Utilities
- Modules: utils.c, philo_header.h
- Responsibility: timing functions, synchronized printing, mutex definitions, shared flags

##### Relationships & Data Flows
1. Main (main_philo.c) reads CLI → calls parse_arg → calls initial_data
2. initial_data allocates philosophers[], forks[] (mutex per fork), global print & state mutexes
3. creat_thread spins up:
– N philosopher threads (each receives pointer to its philo struct)
– 1 monitor thread (receives global state pointer)
- Philosopher Lifecycle (concurrent loops)
– Thinking: no locks
– Eating: acquire left-fork mutex → acquire right-fork mutex → update last_meal_time (protected by meal mutex) → sleep for eat_time → release both fork mutexes
– Sleeping: sleep for sleep_time
– Loop until death flag or eat-count reached
- Monitor’s Role
– Polls each philosopher’s last_meal_time under meal mutex
– If any philosopher starves (current_time – last_meal_time > time_to_die), sets end_flag under flag mutex and signals all threads to terminate
– If all meal_counts ≥ required_eats, sets end_flag and signals graceful termination
- Output Synchronization
– All status prints (timestamps, actions) go through a print mutex to avoid interleaving

##### Architectural Patterns & Design Principles
- Modular C Design: each .c file encapsulates one concern (parsing, init, threading, simulation, monitoring, utils)
- Concurrency via pthreads: one OS thread per philosopher + monitor thread
- Shared-memory synchronization: mutex per fork, one for prints, one for shared-flag/meals
- Deadlock avoidance: enforced fork-acquisition order or asymmetric protocol

– Label every component (Main, Parser, Initializer, Thread Manager, Philosopher Thread, Monitor Thread, Utils)
- Startup control flow →
- Shared-data access ↔
– Annotate critical paths (e.g., fork acquisition order, death detection path)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Modules
    subgraph "Modules"
        Main["Main\n(main_philo.c)"]:::module
        Parser["CLI & Argument Parser\n(parse_arg.c)"]:::module
        Init["Data Initialization\n(initial_data.c)"]:::module
        ThreadMgr["Thread Manager\n(creat_thread.c)"]:::module
        Utils["Shared Utilities & Definitions\n(utils.c & philo_header.h)"]:::module
    end

    %% Shared Resources
    subgraph "Shared Resources" 
        direction TB
        Forks(["forks[] 🔒\n(mutex array)"]):::datastore
        LastMeal(["last_meal_time[] 🔒\n(meal mutex)"]):::datastore
        MealCount(["meal_count[] 🔒\n(meal mutex)"]):::datastore
        EndFlag(["end_flag 🔒\n(flag mutex)"]):::datastore
        PrintMutex(["print_mutex 🔒"]):::datastore
    end

    %% Threads
    subgraph "Threads"
        direction TB
        PhilosopherThreads["Philosopher Threads\n(simulation.c)"]:::thread
        MonitorThread["Monitor Thread\n(monitor.c)"]:::thread
    end

    %% Control Flow
    Main -->|"startup"| Parser
    Parser -->|"validates args"| Init
    Init -->|"allocates data"| ThreadMgr
    ThreadMgr -->|"spawns N threads"| PhilosopherThreads
    ThreadMgr -->|"spawns monitor"| MonitorThread

    %% Data Access (dashed red)
    PhilosopherThreads -.->|acquire/release| Forks
    PhilosopherThreads -.->|update| LastMeal
    PhilosopherThreads -.->|read/write| MealCount
    PhilosopherThreads -.->|prints| PrintMutex

    MonitorThread -.->|polls| LastMeal
    MonitorThread -.->|checks| MealCount
    MonitorThread -.->|sets| EndFlag
    MonitorThread -.->|signals| PhilosopherThreads

    %% Click events
    click Main "https://github.com/m-elhouary/philosopher/blob/main/philo/main_philo.c"
    click Parser "https://github.com/m-elhouary/philosopher/blob/main/philo/parse_arg.c"
    click Init "https://github.com/m-elhouary/philosopher/blob/main/philo/initial_data.c"
    click ThreadMgr "https://github.com/m-elhouary/philosopher/blob/main/philo/creat_thread.c"
    click PhilosopherThreads "https://github.com/m-elhouary/philosopher/blob/main/philo/simulation.c"
    click MonitorThread "https://github.com/m-elhouary/philosopher/blob/main/philo/monitor.c"
    click Utils "https://github.com/m-elhouary/philosopher/blob/main/philo/utils.c"
    click Utils "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click Forks "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click LastMeal "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click MealCount "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click EndFlag "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click PrintMutex "https://github.com/m-elhouary/philosopher/blob/main/philo/philo_header.h"
    click readme1 "https://github.com/m-elhouary/philosopher/blob/main/README.md"
    click readme2 "https://github.com/m-elhouary/philosopher/blob/main/philo/README.md"
    click make "https://github.com/m-elhouary/philosopher/tree/main/philo/Makefile"

    %% Styles
    classDef module fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef thread fill:#87CEEB,stroke:#000,stroke-width:1px
    classDef datastore fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef shared fill:#90EE90,stroke:#000,stroke-width:1px

    linkStyle default stroke:#000,stroke-width:2px
    linkStyle 6,7,8,9,10,11 stroke:red,stroke-dasharray: 5 5,stroke-width:2px
```
