# iantar1/philosophers architecture

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

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

## Overview

##### Project type and purpose
- This is a C-based concurrency demo implementing the Dining Philosophers problem in two flavours:
a) “philo” uses POSIX mutexes
b) “philo_bonus” uses POSIX semaphores
- Its goal is to illustrate thread creation, shared-resource synchronization, race-condition avoidance, and graceful shutdown.

##### File structure
- Top-level:
- README.md – project description and theory
- subject.pdf – problem statement
- philo/ – mutex-based implementation
- philo_bonus/ – semaphore-based implementation
- philo/ and philo_bonus/ are nearly parallel in structure:
- Makefile – compile rules with gcc and -pthread or –lrt
- *.c – core modules (parsing, philosopher routines, utilities)
- *.h – shared data structures (t_philosopher, t_args)
- Key modules in each:
- parce*.c – command-line argument parsing
- philosophers*.c – thread entry point and lifecycle (think, eat, sleep loops)
- utils*.c – time tracking, printing wrappers (ft_printf), cleanup
- bonus version adds utils3.c for semaphore helpers

##### Extract additional insights from the README
- Emphasis on:
- What a thread is, vs a process
- Race conditions
- Semaphores for mutual exclusion

##### Main components
a. Configuration & Parser
- reads N philosophers, time_to_die, time_to_eat, time_to_sleep, optional meals limit
- outputs a shared args struct
b. Main/Controller
- initializes synchronization primitives (mutex array or semaphores)
- spawns N philosopher threads
- joins threads and cleans up resources
c. Philosopher Threads (N instances)
- Each thread runs:
1) attempt to acquire left & right forks (mutex_lock or sem_wait)
2) record last_meal_time, ft_printf(“is eating”)
3) release forks (mutex_unlock or sem_post)
4) ft_printf(“is sleeping”), usleep
5) ft_printf(“is thinking”)
6) loop until death or meal count reached
d. Fork Resources
- philo: array of N pthread_mutex_t
- philo_bonus: two semaphores (“forks” count = N, “write” = 1)
e. Logger (/ft_printf)
- single synchronized output stream to avoid interleaved prints

##### Relationships and interactions
- Main → Parser: read CLI args
- Main → Sync Primitives: initialize mutexes/semaphores
- Main → Philosopher Threads: pthread_create / fork N threads
- Philosopher Threads ↔ Fork Resources: lock/unlock or sem_wait/sem_post
- Philosopher Threads → Logger: ft_printf with a write semaphore/mutex
- Main ← Philosopher Threads: pthread_join, check for termination

##### Architectural patterns & design principles
- Shared-resource synchronization (mutex or semaphore)
- Worker threads pattern with centralized resource manager
- Separation of concerns: parsing, core logic, utilities, I/O

##### Relevant technologies
- Language: C
- Build: Makefile, GCC
- Concurrency: pthreads, POSIX mutex, POSIX semaphores
- Utility: custom ft_printf for thread-safe logging

##### Detail
- Lifecycle loop of each philosopher with states (Think → Eat → Sleep)
- Shared argument struct as a singleton data store
- Termination/cleanup path back to Controller

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Mutex-based Flow"
    ParserMutex1["Parser"]:::module
    UtilsParseMutex["Parser Utils"]:::module
    SharedArgsM["SharedArgs"]:::module
    ControllerM["Controller"]:::module
    MutexInit["Init Mutexes"]:::resource
    PhilosopherThreadsM["Philosopher Threads (N)"]:::thread
    ForksM["Fork Resources (mutex array)"]:::resource
    LoggerM["Logger"]:::logger
    CleanupM["Cleanup"]:::module

    ParserMutex1 --> SharedArgsM
    UtilsParseMutex --> SharedArgsM
    SharedArgsM --> ControllerM
    ControllerM --> MutexInit
    MutexInit --> PhilosopherThreadsM
    PhilosopherThreadsM <--> ForksM
    PhilosopherThreadsM --> LoggerM
    ControllerM --> CleanupM
  end

  subgraph "Semaphore-based Flow"
    ParserSem1["Parser"]:::module
    UtilsParseSem["Parser Utils"]:::module
    SharedArgsS["SharedArgs"]:::module
    ControllerS["Controller"]:::module
    SemInit["Init Semaphores"]:::resource
    PhilosopherThreadsS["Philosopher Threads (N)"]:::thread
    ForksS["Fork Resources (semaphores)"]:::resource
    LoggerS["Logger"]:::logger
    CleanupS["Cleanup"]:::module

    ParserSem1 --> SharedArgsS
    UtilsParseSem --> SharedArgsS
    SharedArgsS --> ControllerS
    ControllerS --> SemInit
    SemInit --> PhilosopherThreadsS
    PhilosopherThreadsS <--> ForksS
    PhilosopherThreadsS --> LoggerS
    ControllerS --> CleanupS
  end

  %% Click Events
  click ParserMutex1 "https://github.com/iantar1/philosophers/blob/main/philo/parce.c"
  click UtilsParseMutex "https://github.com/iantar1/philosophers/blob/main/philo/utils_parcing.c"
  click ControllerM "https://github.com/iantar1/philosophers/blob/main/philo/philosophers.c"
  click philo_utils1 "https://github.com/iantar1/philosophers/blob/main/philo/philo_utils1.c"
  click utils2_mutex "https://github.com/iantar1/philosophers/blob/main/philo/utils2.c"
  click LoggerM "https://github.com/iantar1/philosophers/blob/main/philo/ft_printf.c"

  click ParserSem1 "https://github.com/iantar1/philosophers/blob/main/philo_bonus/parce_bonus.c"
  click UtilsParseSem "https://github.com/iantar1/philosophers/blob/main/philo_bonus/utils_parcing_bonus.c"
  click ControllerS "https://github.com/iantar1/philosophers/blob/main/philo_bonus/philosophers_bonus.c"
  click utils2_sem "https://github.com/iantar1/philosophers/blob/main/philo_bonus/utils2.c"
  click utils3_sem "https://github.com/iantar1/philosophers/blob/main/philo_bonus/utils3.c"
  click LoggerS "https://github.com/iantar1/philosophers/blob/main/philo_bonus/ft_printf.c"

  classDef module fill:#f9f,stroke:#333,stroke-width:1px
  classDef thread fill:#bbf,stroke:#333,stroke-width:1px
  classDef resource fill:#bfb,stroke:#333,stroke-width:1px
  classDef logger fill:#fbf,stroke:#333,stroke-width:1px
```
