# carolina-tcn/philosophers architecture

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

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

## Overview

##### Project type and purpose
- This is a concurrency-focused C simulation of the classic “Dining Philosophers” problem.
- It uses POSIX threads (pthreads) and mutexes to model philosophers (threads) competing for shared forks (resources) without deadlock or starvation.

##### File structure
- inc/philo.h – central data structures and function prototypes
- src/check_input.c – command-line parameter parsing & validation
- src/init.c – initialization of global state, philosopher array, mutexes
- src/main.c – program entry point, high-level orchestration
- src/threads.c – creation and teardown of philosopher threads
- src/philo_actions.c & philo_actions_utils.c – eat/think/sleep behaviors and helper routines
- src/monitoring.c – watcher thread to detect death or completion
- src/utils.c – logging, time utilities, cleanup

##### README for additional insights
- Configurable parameters: number of philosophers, time to die/eat/sleep, optional max-meals
- State transitions: each philosopher alternates between THINK → TAKE FORKS → EAT → RELEASE FORKS → SLEEP
- Synchronization: forks are protected by mutexes to avoid data races, plus a monitor thread checks termination conditions.

##### Diagramming recommendations
◦ Rectangles for modules (Parser, Init, Manager, Monitor)
◦ Rounded rectangles or ovals for threads (Philosopher #1, #2, …, Monitor)
- Blue for control modules (Parser, Init, Manager)
- Green for resources (Forks)
- Orange for active threads (Philosophers, Monitor)
- Directionality:

##### Detail without over-complicating
- Every mutex and thread is represented, so the engineer can see how deadlock is avoided by design.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Main["Program Entry Point / Orchestration"]:::control
    Parser["CLI Input Parser"]:::control
    Initializer["Initializer Module"]:::control
    Manager["Philosopher Manager"]:::control

    subgraph "Runtime Environment"
      direction TB
      Threads["Philosopher Threads (N instances)"]:::thread
      subgraph "Fork Resources"
        direction LR
        Forks["Fork Mutexes (N)"]:::resource
      end
      Monitor["Monitor Thread"]:::thread
    end

    Logger["Logger / Output"]:::control

    Main -->|starts| Parser
    Parser -->|validated params| Initializer
    Initializer -->|constructed shared state| Manager
    Manager -->|spawn threads| Threads
    Threads -->|lock/unlock forks| Forks
    Threads -->|log status| Logger
    Monitor -->|polls shared state| Manager
    Monitor -->|log status| Logger

    click Main "https://github.com/carolina-tcn/philosophers/blob/main/src/main.c"
    click Parser "https://github.com/carolina-tcn/philosophers/blob/main/src/check_input.c"
    click Initializer "https://github.com/carolina-tcn/philosophers/blob/main/src/init.c"
    click Manager "https://github.com/carolina-tcn/philosophers/blob/main/src/threads.c"
    click Threads "https://github.com/carolina-tcn/philosophers/blob/main/src/philo_actions.c"
    click Forks "https://github.com/carolina-tcn/philosophers/blob/main/inc/philo.h"
    click Monitor "https://github.com/carolina-tcn/philosophers/blob/main/src/monitoring.c"
    click Logger "https://github.com/carolina-tcn/philosophers/blob/main/src/utils.c"

    classDef control fill:#ADD8E6,stroke:#000000,stroke-width:1px
    classDef thread fill:#FFA500,stroke:#000000,stroke-width:1px
    classDef resource fill:#90EE90,stroke:#000000,stroke-width:1px
```
