1  # Philosopher Simulation
  2  
  3  ## Overview
  4  
  5  This is a simulation of the classic "Dining Philosophers" problem, which illustrates the challenges of resource sharing and synchronization in concurrent programming.
  6  This simulation makes use of `pthreads` to create multiple threads representing philosophers, each of whom needs to acquire two forks (resources) to eat, while only having one.
  7  To achieve this, the simulation uses a mutex lock to ensure that only one philosopher can access a fork at a time.
  8  
  9  ## Requirements
 10  
 11  - C compiler (here Clang is used)
 12  - the `pthreads` library
 13  - `make` (optional, for building the project)
 14  - `mold` (optional, for faster linking)
 15  - `valgrind` (optional, for memory leak detection)
 16  
 17  ## Compilation
 18  
 19  To compile the project, you can use the provided `Makefile`. Simply run:
 20  
 21  ```bash
 22  make
 23  ```
 24  
 25  This will create an executable named `philo`.
 26  
 27  To compile the 'bonus' version of the project, which includes the `philo_bonus` executable, run:
 28  
 29  ```bash
 30  make bonus
 31  ```
 32  
 33  This will create an additional executable named `philo_bonus`.
 34  
 35  To compile the project with `mold` for faster linking, simply install `mold`, and the
 36  Makefile will automatically use it for linking. You can check if `mold` is installed by running:
 37  
 38  ```bash
 39  mold --version
 40  ```
 41  
 42  If `mold` is not installed, the Makefile will fall back to the default linker,
 43  which is usually `ld`. You can install `mold` using your package manager. For example, on Ubuntu, you can run:
 44  
 45  ```bash
 46  sudo apt install mold
 47  ```
 48  
 49  ## Usage
 50  
 51  To run the simulation, use the following command:
 52  
 53  ```bash
 54  ./philo [number_of_philosophers] [time_to_die] [time_to_eat] [time_to_sleep] [number_of_times_each_philosopher_must_eat]
 55  ```
 56  
 57  In which:
 58  
 59  - `number_of_philosophers`: The number of philosophers (and forks) in the simulation.
 60  - `time_to_die`: The time in milliseconds that a philosopher can go without eating before they die.
 61  - `time_to_eat`: The time in milliseconds that a philosopher takes to eat.
 62  - `time_to_sleep`: The time in milliseconds that a philosopher takes to sleep.
 63  - `number_of_times_each_philosopher_must_eat`: `OPTIONAL`: The number of times each philosopher must eat before the simulation ends. If not provided, the simulation will run indefinitely until a philosopher dies.
 64  
 65  ### Examples
 66  
 67  ```bash
 68  ./philo 5 800 200 200
 69  ```
 70  
 71  This will create a simulation with 5 philosophers, where each philosopher can go 800 milliseconds without eating before they die, and takes 200 milliseconds to eat and sleep.
 72  
 73  ```bash
 74  ./philo 5 800 200 200 7
 75  ```
 76  
 77  This will create a simulation with 5 philosophers, where each philosopher can go 800 milliseconds without eating before they die, and takes 200 milliseconds to eat and sleep. Each philosopher must eat 7 times before the simulation ends.
 78  
 79  ```bash
 80  ./philo_bonus 5 800 200 200
 81  ```
 82  
 83  This will create a simulation with 5 philosophers, where each philosopher can go 800 milliseconds without eating before they die, and takes 200 milliseconds to eat and sleep. Each philosopher must eat 7 times before the simulation ends.
 84  
 85  ```bash
 86  ./philo_bonus 5 800 200 200 7
 87  ```
 88  
 89  This will create a simulation with 5 philosophers, where each philosopher can go 800 milliseconds without eating before they die, and takes 200 milliseconds to eat and sleep. Each philosopher must eat 7 times before the simulation ends.
 90  
 91  ## Memory Leak Detection
 92  
 93  To check for memory leaks, you can use `valgrind`. Run the simulation with `valgrind` like this:
 94  
 95  ```bash
 96  valgrind --leak-check=full ./philo [number_of_philosophers] [time_to_die] [time_to_eat] [time_to_sleep] [number_of_times_each_philosopher_must_eat]
 97  ```
 98  
 99  This will run the simulation under `valgrind` and check for memory leaks. If there are any memory leaks, `valgrind` will report them in the output.
100  
101  ## Licence
102  
103  This project uses both the MIT and Apache 2.0 licences,
104  you may choose which one you prefer based on your needs.
105  
106  ## Licence Information
107  
108  This project is dual-licensed under both MIT and Apache 2.0 licence. Choose the one that better suits your needs.
109  
110  ### MIT Licence
111  
112  **Description:** A permissive licence with very few restrictions.
113  
114  ✅ **Permissions:**
115  
116  - Commercial use
117  - Modification
118  - Distribution
119  - Private use
120  
121  📋 **Conditions:**
122  
123  - Licence and copyright notice must be included
124  
125  ⚠️ **Limitations:**
126  
127  - No liability
128  - No warranty
129  
130  ### Apache Licence 2.0
131  
132  **Description:** A permissive licence similar to MIT but with additional protections.
133  
134  ✅ **Permissions:**
135  
136  - Commercial use
137  - Modification
138  - Distribution
139  - Patent use
140  - Private use
141  
142  📋 **Conditions:**
143  
144  - Licence and copyright notice must be included
145  - Changes must be documented
146  
147  ⚠️ **Limitations:**
148  
149  - Trademark use not granted
150  - No liability
151  - No warranty