VaultOS

A concurrent banking simulation engine demonstrating five core operating system concepts — threading, synchronization, IPC, deadlock prevention, and virtual memory — working in concert within a single runnable C program.

---

Table of Contents

• Overview
• OS Concepts Demonstrated
• Architecture
• Directory Structure
• Prerequisites
• Building
• Running the Simulation
• Configuration
• Expected Output
• Running Tests
• Documentation
• Team
• License

---

Overview

VaultOS models a concurrent bank branch. Customer requests arrive as POSIX threads and are dispatched through a scheduling layer (FCFS, Priority, Round Robin). A central bank server processes transactions asynchronously over a POSIX message queue. Shared account state is protected by mutex locks and counting semaphores. Loan requests are evaluated by Banker's Algorithm to guarantee deadlock freedom. Each customer's data footprint is paged through a simulated frame table with configurable FIFO or LRU replacement.

The simulation produces:

• Gantt charts and per-thread metrics (AT, BT, ST, CT, TAT, WT) for all three scheduling algorithms
• A three-algorithm comparison table (average WT and TAT)
• A timestamped IPC event log (logs/ipc_log.txt)
• Banker's Algorithm state tables before and after each loan decision
• A FIFO vs LRU page fault comparison across frame counts 2, 3, and 4

---

OS Concepts Demonstrated

Concept	Implementation
Threading & Scheduling	pthreads · FCFS · Non-preemptive Priority · Round Robin
Synchronization	pthread_mutex_t account locks · POSIX sem_t teller windows
Inter-Process Communication	POSIX message queues · unnamed pipes · producer-consumer pattern
Deadlock Prevention	Banker's Algorithm — Safety Check + Resource-Request Algorithm
Memory Management	Paged memory simulation · FIFO replacement · LRU replacement

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                        main.c                           │
│              (integration & demo orchestration)         │
└────────┬────────┬────────┬──────────────┬──────────────┘
         │        │        │              │
         ▼        ▼        ▼              ▼
  ┌──────────┐ ┌──────┐ ┌─────────┐ ┌───────────────┐
  │ thread_  │ │ ipc_ │ │ sync_   │ │ deadlock_     │
  │scheduler │ │ bus  │ │ manager │ │ manager       │
  └──────────┘ └──────┘ └─────────┘ └───────────────┘
       │            │         │              │
       └────────────┴─────────┴──────────────┘
                         │
                    ┌────┴─────┐
                    │ common.h │  ← single shared header
                    │ globals.c│    all structs, enums,
                    └──────────┘    constants, externs
                         │
               ┌─────────┴──────────┐
               ▼                    ▼
       ┌──────────────┐    ┌──────────────────┐
       │memory_manager│    │     logger       │
       │ (FIFO / LRU) │    │  (thread-safe)   │
       └──────────────┘    └──────────────────┘

All modules share a single header (src/common/common.h). No module includes another module's header directly — cross-module calls are declared as forward declarations in common.h. This keeps the dependency graph acyclic and allows every translation unit to be compiled independently.

---

Directory Structure

VaultOS/
├── src/
├── ├──gui/
│   │  ├── gui.h
│   │  └── gui.c
│   ├── common/
│   │   └── common.h                # Shared header — all structs, enums, constants
│   ├── thread_scheduler/
│   │   ├── thread_scheduler.c      # spawn_customer, join_customer
│   │   ├── run_scheduler.c         # FCFS, Priority, Round Robin dispatch
│   │   └── gantt_chart.c           # Gantt chart generation
│   ├── sync_manager/
│   │   ├── account_mutex.c         # Per-account pthread_mutex_t lifecycle
│   │   └── sync_teller_windows.c   # Counting semaphore for teller concurrency
│   ├── ipc_bus/
│   │   ├── bank_ipc_server.c       # POSIX message queue server thread
│   │   ├── producer_consumer.c     # Bounded buffer pattern (pipes)
│   │   └── ipc_internal.h          # Internal IPC types
│   ├── deadlock_manager/
│   │   ├── deadlock_guard.c        # Resource-request algorithm driver
│   │   └── safety_algorithm.c      # Safe-sequence finder
│   ├── memory_manager/
│   │   ├── memory_manager.c        # Page table, frame management
│   │   ├── fifo.c                  # FIFO page replacement
│   │   ├── lru.c                   # LRU page replacement
│   │   └── page_stats.c            # Fault/hit ratio computation
│   ├── accounts/
│   │   ├── account_manager.c       # Account CRUD operations
│   │   └── account_manager.h
│   ├── logger/
│   │   └── logger.c                # Thread-safe timestamped file logger
│   ├── globals.c                   # Global variable definitions
│   └── main.c                      # Entry point and integration harness
│
├── tests/
│   ├── thread_scheduler/
│   │   └── test_thread_scheduler.c
│   ├── ipc_bus/
│   │   └── test_ipc_bus.c
│   ├── sync_manager/
│   │   └── test_sync_manager.c
│   ├── deadlock_manager/
│   │   └── test_deadlock_manager.c
│   ├── memory_manager/
│   │   └── test_memory_manager.c
│   ├── accounts/
│   │   └── test_account_manager.c
│   ├── logger/
│   │   └── test_logger.c
│   └── CMakeLists.txt
│
├── logs/
│   └── ipc_log.txt                 # Runtime IPC event log (auto-created)
├── data/                           # Simulation input data (optional)
├── reports/                        # Generated reports output directory
├── docs/                           # Additional documentation
├── CMakeLists.txt
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

---

Prerequisites

Operating System: Linux (Ubuntu 20.04+ recommended) or any POSIX-compliant system. Windows users should use WSL2.

Compiler: GCC ≥ 9.0

sudo apt install gcc
gcc --version

Build System: CMake ≥ 3.16

sudo apt install cmake

Libraries — all POSIX standard, no external installs required:

Library	Purpose	Link flag
pthread	POSIX threads, mutexes, semaphores	-lpthread
mqueue	POSIX message queues	-lrt
time	POSIX clocks	(part of libc)

Optional — for generating page fault graphs:

pip install matplotlib

---

Building

Clone the repository and create an out-of-source build directory:

git clone https://github.com/your-org/VaultOS.git
cd VaultOS
mkdir build && cd build
cmake ..
make

Build targets:

Target	Command	Description
All	make	Simulation binary + all test binaries
Simulation only	make vaultos	Produces build/vaultos
Specific test	make test_memory_manager	Builds one test binary
Clean	make clean	Removes all compiled artifacts

Rebuild after changing constants:

cd build && make clean && make

---

Running the Simulation

From the project root (not inside build/):

./build/vaultos

The simulation runs all five OS concept demonstrations end-to-end and prints nine labeled output sections to stdout. The IPC log is written concurrently to logs/ipc_log.txt.

Capture full output to a file:

./build/vaultos > logs/sample_output.txt 2>&1

Cleanup stale IPC queue (if the program exits abnormally):

rm -f /dev/mqueue/bank_ipc_queue

---

Configuration

All tunable constants are defined at the top of src/common/common.h. After changing any value, do a clean rebuild.

Constant	Default	Description
MAX_CUSTOMERS	64	Maximum concurrent customer threads
MAX_ACCOUNTS	64	Number of bank accounts in simulation
MAX_RESOURCES	8	Resource types for Banker's Algorithm
MAX_PROCESSES	16	Maximum loan applicant processes
MAX_PAGES	32	Pages per customer memory footprint
MAX_FRAMES	8	Physical frames available
PAGE_SIZE_KB	4	Simulated page size in kilobytes
IPC_BUFFER_SIZE	5	Bounded buffer slots (producer-consumer)
TIME_QUANTUM_MS	2	Round Robin time quantum in milliseconds
TELLER_WINDOWS	2	Semaphore initial value (concurrent tellers)
MAX_TX_HISTORY	512	Maximum transaction records stored

---

Expected Output

A full simulation run prints sections in this order:

[Feature 1]  MUTEX DEMO          — race condition without / with mutex
[Feature 8]  TELLER SEMAPHORE    — 3 threads blocked on 2 teller windows
[Feature 3]  IPC + MUTEX         — customer transaction dispatch
[Feature 7]  BANKER'S ALGORITHM  — state tables + GRANTED / DENIED decisions
[Feature 4]  PAGE REPLACEMENT    — FIFO vs LRU across 2, 3, 4 frames
[Feature 5]  FCFS SCHEDULING     — metrics table + Gantt chart
[Feature 6]  PRIORITY SCHEDULING — metrics table + Gantt chart
             ROUND ROBIN         — metrics table + Gantt chart
[Feature 9]  COMPARISON TABLE    — average WT and TAT for all three algorithms

IPC log format (logs/ipc_log.txt):

[14:32:01.042] CUST-03  DEPOSIT     500.00  SUCCESS
[14:32:01.055] CUST-07  WITHDRAW    200.00  SUCCESS
[14:32:01.061] CUST-02  LOAN_REQ   1000.00  DENIED

Banker's Algorithm test cases:

Case	Setup	Expected
Safe	P0-P3 allocated; available = {3,3,4}; P0 requests {1,0,2}	GRANTED — safe sequence printed
Unsafe	Same state; P1 requests {3,3,0}	DENIED — would leave unsafe state
Boundary	Request exactly equal to available	Safety check runs; result depends on need matrix

Page replacement reference string: 0 → 1 → 2 → 3 → 0 → 1 → 4 → 0 → 1 → 2 → 3 → 4

---

Running Tests

cd build
ctest --output-on-failure

Run individual test binaries:

./build/tests/thread_scheduler/test_thread_scheduler
./build/tests/ipc_bus/test_ipc_bus
./build/tests/sync_manager/test_sync_manager
./build/tests/deadlock_manager/test_deadlock_manager
./build/tests/memory_manager/test_memory_manager
./build/tests/accounts/test_account_manager
./build/tests/logger/test_logger

---

Documentation

File	Contents
docs/01_components.md	Per-module internal design — data structures, algorithms, and public API
docs/02_dependencies.md	Full cross-component dependency analysis and how the IPC/SyncManager circular dependency is resolved via dependency injection
docs/03_gui_endpoints.md	Guide for adding a GUI layer — six fire-and-forget push functions, rendering hints, field reference
docs/04_build_sequence.md	Thirteen features in dependency order — owner, prerequisites, deliverable, unblocks

---

Team

Name	Student ID	Responsibilities
Muhammad Zain	24F-0531	Thread creation, FCFS / Priority / Round Robin scheduling, metrics (TAT, WT), Gantt charts
Abdullah Ahmad	24F-0618	Mutex locks, semaphores, POSIX message queue & pipe IPC, producer-consumer pattern, IPC logging, module integration, build system
Muhammad Hassaan	24F-0736	Banker's Algorithm (safety check + resource-request), paged memory simulation, FIFO and LRU replacement, fault/hit metrics

CL2006 Operating System Lab · Spring 2026 · FAST-NUCES Chiniot-Faisalabad · BS-4-A/B

---

License

This project is licensed under the MIT License. See LICENSE for details.

All code is original work by Group 2. Plagiarism detection will be applied during assessment.