ThreadNexus: Multithreaded Networking in C

ThreadNexus is a small C project exploring sockets, threads, and shared state. It includes a minimal server loop, a player/score database, and utilities for testing concurrency behavior.

For more background on Linux environments and code I/O, see: Linux Operating Systems - rsiddiq.com.

Features

• TCP Server Loop: Start/stop a simple TCP server using pthreads. Note: by default, the server is started inside the test binary.
• Player Database: In-memory player registry with basic CRUD.
• Thread Utilities: Helpers for simulating slow work and exercising race conditions.
• Modular Headers: Clear separation between server.h, database.h, and threadnexus.h.
• Portable Build: Standard Makefile for Linux/macOS/WSL.

Project Layout

Note: The layout below omits transient build artifacts (e.g., bin/, build/, dist/) that are ignored in version control.

ThreadNexus/
├── README.md
└── ThreadNexus
    ├── .gitignore
    ├── Makefile
    ├── README.md
    ├── src
    │   ├── common.c
    │   ├── common.h
    │   ├── database.c
    │   ├── database.h
    │   ├── server.c
    │   ├── server.h
    │   ├── threadnexus.c
    │   └── threadnexus.h
    ├── tests
    │   ├── unittests_conditions.c
    │   ├── unittests_locks.c
    │   └── unittests_server.c
    ├── unit_tests
    └── unit_tests.c

Build Requirements

• GCC or Clang
• make (recommended)
• POSIX threads (usually available by default on Linux/macOS)
• Unix-like environment (Linux, macOS, WSL)
• Criterion unit test framework (libcriterion-dev on Debian/Ubuntu)

Build

make            # build
make clean      # clean artifacts

Quick Start

Make sure you are in the directory that contains the Makefile (for this zip, that’s typically ThreadNexus/ThreadNexus).

# 0) (Ubuntu/WSL) Install test dependency
sudo apt-get update && sudo apt-get install -y libcriterion-dev

# 1) Build
make

# 2) Run tests (this starts the server internally on the default port 5005)
./unit_tests

# 3) (Optional) In another terminal, connect while tests are running
nc 127.0.0.1 5005

Default Port: The test-run server listens on 5005, as set in src/server.c within setup().

Binaries

• unit_tests — primary executable built by the Makefile. It launches the server (port 5005) and runs the Criterion tests.
• No standalone threadnexus server binary is produced by default. If you want one, add a small server_main.c and a make run target (happy to provide a patch).

Code Overview

• server.h / server.c: Socket setup, listen/accept loop, per-connection handler threads.
• database.h / database.c: Player database abstraction and synchronization primitives around shared data.
• threadnexus.h / threadnexus.c: Common definitions, constants, and glue across modules.
• tests/*.c: Criterion-based unit tests; they initialize and exercise the server/database.

Concurrency Notes

• Shared data access should be wrapped in mutex-protected functions.
• Long-running operations (e.g., artificial delays) are isolated to avoid blocking the accept loop.
• Thread lifetimes are joined or detached to avoid leaks; ensure clean shutdown on SIGINT.

Testing

• Tests are implemented with Criterion under tests/ and executed by ./unit_tests.
• For quick manual checks, run ./unit_tests and use nc/telnet to send simple commands to 127.0.0.1:5005 while tests hold the server open.

Roadmap

• Command protocol for client/server interaction
• Persistent storage of player data
• Graceful shutdown hooks and signal handling
• CI workflow (lint + build + tests)