# Assignment 2

## UVic CSC360 Spring 2024

**Due Monday March 4, at 11:55 pm** via `push` to your `gitlab.csc`

 repository.

## Programming Platform

For this assignment your code must work in the Jupyterlab environment

provisioned for you at `https://jhub-cosi.uvic.ca/`.  You may already

have access to your own Unix system (e.g., Ubuntu, Debian, Cygwin on

Windows 11, macOS with MacPorts, etc.) yet we recommend you work as

much as possible with your CSC360 JupyterLab environment. Bugs in

systems programming tend to be platform-specific and something that

works perfectly at home may end up crashing on a different

computer-language library configuration. (We cannot give marks for

submissions of which it is said “It worked on Visual Studio!”)

## Individual work

This assignment is to be completed by each individual student (i.e.,

no group work).  Naturally you will want to discuss aspects of the

problem with fellow students, and such discussions are encouraged.

However, **sharing of code is strictly forbidden**. If you are still

unsure about what is permitted or have other questions regarding

academic integrity, please direct them as soon as possible to the

instructor. (Code-similarity tools will be run on submitted programs.)

Any fragments of code found on the web and used in your solution must

be properly cited where it is used (i.e., citation in the form of a

comment given source of code).

## Use of `gitlab.csc.uvic.ca`

Each student enrolled in the course has been assigned a Git repository

at `gitlab.csc.uvic.ca`. For example, the student having Netlink ID

`johnwick` would have their CSC 360 repository at this location:

```

https://gitlab.csc.uvic.ca/courses/2024011/CSC360_COSI/assignments/johnwick/coursework-os

```

Please form the address of your repository appropriately **and if you

have not already done so**  perform a `git clone` in your jupyterlab

environment. You are also able to access this repository by going to

`https://gitlab.csc.uvic.ca` (and use your Netlink username and

password to log in at that page). **If you have already used `clone` to

obtain your repository** the use `git pull` to retrieve files for this

assignment.

---

## Goals of this assignment

This is an opportunity for you to use -- and perhaps wrestle with --

concurrency in an imperative programming language such as C. Some of

the ideas you may use here for solving the problems of cooperating

and competing threads/tasks can be used in other languages such as Java.

1. Write a program (`kosmos-sem.c`) that solves the **Kosmos-methoxy-radical**

problem with the use of semaphores.

2. Write a program (`kosmos-mcv.c`) that solves the **Kosmos-methoxy-radical**

problem with the use of mutexes and condition variables.

---

## The **Kosmos-methoxy radical** problem

You are hired by an interstellar civilization of much greater intelligence that

ours (!!) who are seeding the universe with the building blocks needed for a

one of their major projects. The specific task you have agreed to help solve

for them is to manage the chemical reaction needed to form **methoxy radicals**

(which is made up of one carbon atom, one oxygen atom, and three hydrogen atoms).

Despite the civilization's greater intelligence, they are having trouble getting

the carbon, oxygen, and hydrogen atoms to combine correctly due to some serious synchronization

problems. They are able to create each atom (i.e., one atom equals one thread), and so

the challenge is to get one carbon thread, three hydrogen threads, and one oxygen thread all together at the

same time, regardless of the number or order of thread/atom creation.

Each carbon atom invokes a function named `c_ready()`when it is ready to react;

each hydrogen atom invokes a function named `h_ready()`when it is ready to react; and finally each oxygen atom invokes a function named `o_ready()` when it is ready to react.

For this problem you are to complete the code for `c_ready`, `h_ready`, and `o_ready`, adding

whatever code and data structures are needed to solve the problem.

Here are some other requirements for solutions:

* Skeleton files that will help you get started on the goal are available in

  this repository.

* The `h_ready`, `c_ready`, and `o_ready` functions must only delay until there are at least

  one carbon, one oxygen, and three hydrogen atoms ready to combine into the radical.

* **You are not permitted** to wait until all threads / atoms are

created such that you then match up atoms once you know what exists.

This means your solution must work when the next atom/thread created

is a hydrogen atom when there exist already one carbon, one oxgygen,

and two hydrogens; or when the next atom/thread created is a carbon

atom when there exist already one oxygen and three hydrogen; and so

forth and so on.

* When an arriving atom/thread determines that a radical can be made,

then that atom/thread must cause the radical to be made to indicate

the identities of the carbon atom, oxygen atom, and hydrogen atoms.

Below is an example showing the format of the report, where each line

indicates the atoms in a radical, and the atom/thread in parentheses

was the one that initiated the creation of the radical. For example,

below the 7th radical consists of carbon atom 7, oxygen atom 7,

hydrogen atoms 21 & 22 & 23, and it was the carbon atom that triggered

the creation of the radical