From e0ae2727d0a48478a61d205a75aa5be09776f79c Mon Sep 17 00:00:00 2001 From: Yurii Korolkov Date: Mon, 15 Jun 2026 23:07:05 +0300 Subject: [PATCH] Udate README --- README.md | 396 +++++++++++++++++++++++++++++++++++++++++++++++++++++ ReadMe.txt | 23 ---- 2 files changed, 396 insertions(+), 23 deletions(-) create mode 100644 README.md delete mode 100644 ReadMe.txt diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f55ac4 --- /dev/null +++ b/README.md @@ -0,0 +1,396 @@ +# Shop Simulator + +[![Shop Simulation](https://github.com/Yurii-Kor/Shop-Simulator/actions/workflows/shop-simulation.yml/badge.svg)](https://github.com/Yurii-Kor/Shop-Simulator/actions/workflows/shop-simulation.yml) + +A concurrent shop simulation written in C using processes, POSIX threads, System V shared memory, and semaphores. + +The project demonstrates a writer-aware, turnstile-based approach to the [readers–writers problem](https://en.wikipedia.org/wiki/Readers%E2%80%93writers_problem): multiple readers may access shared data concurrently, while writers receive exclusive access. + +
+How the simulation works + +
+ +The manager process initializes the shared resources, starts customer and sales-agent processes, controls the simulation lifetime, and performs the final cleanup. + +```mermaid +flowchart TD + A["Program start"] --> B["Parse and validate arguments
Prepare the runtime IPC token"] + + B --> C["Initialize shared resources
────────────
Shared memory: products, buying boards, board count, reader counters
Semaphores per resource: Order, Readers, Access"] + + C --> D["Fork worker processes"] + + D --> M["Manager process
Wait for the 29-second simulation window"] + D --> CU0["Customer processes"] + D --> SA0["Sales-agent processes"] + + subgraph CUSTOMER["Customer loop"] + direction TD + + CU0 --> CU1["Read the product menu"] + CU1 --> CU2["Choose a product and amount"] + CU2 --> CU3["Read the buying boards"] + CU3 --> CU4{"Can a new order be created?"} + + CU4 -->|Yes| CU5["Add a buying board
Exclusive write access"] + CU4 -->|No| CU1 + CU5 --> CU1 + end + + subgraph AGENT["Sales-agent loop"] + direction TD + + SA0 --> SA1["Read the buying boards"] + SA1 --> SA2{"Pending order found?"} + + SA2 -->|No| SA1 + SA2 -->|Yes| SA3["Revalidate and mark the order as done
Exclusive write access"] + SA3 --> SA4["Update product totals
Exclusive write access"] + SA4 --> SA1 + end + + M --> H["Send SIGTERM and wait for worker processes"] + + H -. SIGTERM .-> CU0 + H -. SIGTERM .-> SA0 + + H --> I["Print the simulation summary
Income · Total orders · Pending orders"] + I --> J["Detach shared memory
Remove semaphores"] + + classDef manager fill:#dbeafe,stroke:#2563eb,color:#0f172a,stroke-width:2px; + classDef shared fill:#ede9fe,stroke:#7c3aed,color:#1f2937,stroke-width:2px; + classDef customer fill:#dcfce7,stroke:#16a34a,color:#14532d,stroke-width:2px; + classDef agent fill:#ffedd5,stroke:#ea580c,color:#7c2d12,stroke-width:2px; + + class A,B,D,M,H,I,J manager; + class C shared; + class CU0,CU1,CU2,CU3,CU4,CU5 customer; + class SA0,SA1,SA2,SA3,SA4 agent; +``` + +### Diagram legend + +* **Blue** — manager lifecycle and application control. +* **Purple** — shared IPC resources. +* **Green** — customer operations. +* **Orange** — sales-agent operations. + +
+ +
+Process roles + +
+ +### Manager + +The parent process: + +* validates the simulation configuration; +* creates shared memory and semaphores; +* starts customer and sales-agent processes; +* controls the simulation duration; +* terminates and waits for child processes; +* prints the final result; +* removes all IPC resources. + +### Customers + +Each customer runs in a separate process and repeatedly: + +1. reads the shared product menu; +2. chooses a product and amount; +3. reads the shared buying board; +4. checks the status of the previous order; +5. optionally adds a new order. + +Product and buying-board reads may run concurrently with other readers. Adding an order requires exclusive writer access. + +### Sales agents + +Each sales agent runs in a separate process and repeatedly: + +1. reads the shared buying board; +2. searches for a pending order; +3. revalidates the selected order under exclusive access; +4. marks the order as completed; +5. updates the total number of ordered products. + +Revalidation prevents two sales agents that observed the same pending order from processing it twice. + +
+ +
+Synchronization model + +
+ +The products and buying board are independent shared resources. + +Each resource uses three System V semaphores: + +| Semaphore | Responsibility | +| --------- | ---------------------------------------------------------------------------- | +| `Order` | Acts as a turnstile and prevents new readers from bypassing a waiting writer | +| `Readers` | Protects the shared active-reader counter | +| `Access` | Provides exclusive writer access and is held collectively by active readers | + +### Reader flow + +The first reader locks `Access`, allowing subsequent readers to enter concurrently. + +The final active reader releases `Access`. + +```text +lock Order +lock Readers + +if first reader: + lock Access + +increment reader count + +unlock Readers +unlock Order + +read shared data + +lock Readers +decrement reader count + +if last reader: + unlock Access + +unlock Readers +``` + +### Writer flow + +A writer first closes the `Order` turnstile and then waits for exclusive access. + +```text +lock Order +lock Access +unlock Order + +modify shared data + +unlock Access +``` + +While the writer is waiting for active readers to finish, new readers cannot bypass it through the turnstile. + +This provides: + +* concurrent access for readers; +* exclusive access for writers; +* protection of shared reader counters; +* resistance to writer starvation. + +The synchronization model is based on the classic [readers–writers problem](https://en.wikipedia.org/wiki/Readers%E2%80%93writers_problem). + +
+ +
+Shared resources + +
+ +The simulator maintains two main shared data areas. + +### Products + +The product storage contains: + +* product ID; +* product name; +* price; +* total ordered amount. + +Customers read the product list, while sales agents update order totals. + +### Buying boards + +The buying-board storage contains: + +* board ID; +* customer ID; +* product ID; +* requested amount; +* completion status. + +Customers add new boards, while sales agents find and complete pending orders. + +### Reader counters + +Active-reader counters are also stored in shared memory so that all forked processes observe the same synchronization state. + +The simulator creates its System V IPC key source automatically at runtime: + +```text +.runtime/ipc.token +``` + +No manually prepared key files are required. + +
+ +
+Build and run + +
+ +The simulator is intended for Linux or WSL and requires GCC with POSIX thread support. + +### Compile + +```bash +gcc \ + -std=gnu11 \ + -Wall \ + -Wextra \ + -Wpedantic \ + -pthread \ + shop_simulator.c \ + -o shop-simulator +``` + +### Run with default values + +```bash +./shop-simulator +``` + +The default configuration is: + +| Argument | Default | Allowed range | +| ------------ | ------: | ------------: | +| Products | 10 | 1–10 | +| Sales agents | 2 | 1–4 | +| Customers | 4 | 1–10 | + +### Run with custom values + +Arguments must be passed in this order: + +```text +products sales-agents customers +``` + +Example: + +```bash +./shop-simulator 5 2 4 +``` + +The simulation runs for approximately 29 seconds. + +At the end, it prints: + +* total income; +* total number of boards; +* number of pending orders; +* final product statistics; +* final buying-board contents. + +### Stop the simulation manually + +Press: + +```text +Ctrl+C +``` + +The manager will request graceful termination, wait for all worker processes, print the current summary, and remove the IPC resources. + +
+ +
+GitHub Actions demo + +
+ +The `Shop Simulation` workflow contains two dependent jobs. + +### Build simulator + +The build job: + +* checks out the repository; +* compiles the source using GCC; +* enables strict compiler warnings; +* treats warnings as build errors; +* uploads the compiled executable as an artifact. + +### Run simulation + +The simulation job: + +* starts only after a successful build; +* downloads the compiled executable; +* runs the simulator with a timeout; +* records the console output; +* verifies that the final summary was produced; +* uploads the simulation log as an artifact. + +The workflow runs automatically for pushes and pull requests. + +### Run the workflow manually + +To run the simulator with custom parameters: + +1. fork this repository; +2. open the **Actions** tab in the fork; +3. select **Shop Simulation**; +4. choose **Run workflow**; +5. enter the desired number of products, sales agents, and customers. + +GitHub Actions then compiles and executes the simulator in a Linux environment. + +
+ +
+Project structure + +
+ +```text +Shop-Simulator/ +├── .github/ +│ └── workflows/ +│ └── shop-simulation.yml +├── .gitignore +├── README.md +└── shop_simulator.c +``` + +| File | Purpose | +| --------------------------------------- | --------------------------------------------------------------------------- | +| `shop_simulator.c` | Simulation, process management, shared memory, semaphores, and worker logic | +| `.github/workflows/shop-simulation.yml` | Automated compilation and simulation workflow | +| `.gitignore` | Excludes runtime files, local binaries, and generated logs | +| `README.md` | Project documentation | + +
+ +
+Project background + +
+ +This project was originally created as an operating-systems and concurrency exercise. + +It was later refactored to improve: + +* interprocess readers–writers synchronization; +* protection of shared counters; +* concurrent order revalidation; +* IPC resource management; +* argument validation; +* graceful process shutdown; +* automated compilation and execution through GitHub Actions. + +The project is intended as an educational demonstration of process coordination and shared-resource synchronization in C. + +
diff --git a/ReadMe.txt b/ReadMe.txt deleted file mode 100644 index f78cce5..0000000 --- a/ReadMe.txt +++ /dev/null @@ -1,23 +0,0 @@ -OS : Linux Ubuntu -fp.c : main File of the project -keys/ : folder with files for keys generating - -the program can be runned with 3 arguments : -1) Number of different items/products (up to 10) -2) Number of sale assistants (up to 3) -3) Number of customers (up to 10) - -Default values : -1) Number of different items/products = 10; -2) Number of sale assistants = 2; -3) Number of customers = 4; - -The program shows the multiproces relationships and solves reader-writer problem. -The program has: - 1. shared memory - 2. proceses "assistant" - 3. proceses "customer" - -This program is working for 30 sec. -Durin this time, subproceses can read or write data to shared memory using thread functions. -Processes access shared memory in random order. \ No newline at end of file