Core Module

The Core module provides the fundamental building blocks and runtime primitives for the Join framework. It includes networking, concurrency, I/O, and utility components.

🌐 Networking

MAC Address

48-bit MAC address representation with parsing, formatting, and comparison.

IP Address

IP address abstraction supporting both IPv4 and IPv6: parsing, formatting, network and broadcast address calculation, and comparison.

Endpoints

Network endpoint representation combining an IP address and a port, with support for both address families.

Protocol

Protocol definitions and type system for the different socket kinds.

Sockets

Socket abstractions for various protocols:

• TCP — stream-oriented reliable connections
• UDP — connectionless datagram protocol
• TLS/SSL — encrypted secure communications
• Unix Domain — inter-process communication (stream and datagram)
• Raw — direct IP packet access
• ICMP — Internet Control Message Protocol
• Netlink — Linux kernel communication

Acceptors

Server-side socket abstractions for accepting incoming connections: TCP, TLS, and Unix stream.

Socket Streams

Buffered stream interface for sockets with std::iostream integration, including stream operators (<<, >>).

⚡ Reactor

Event-driven I/O multiplexing built on Linux epoll:

• Reactor — embeddable event loop; call run() to start, stop() to terminate
• ReactorThread — singleton wrapper that owns a Reactor on a dedicated background thread
• EventHandler — interface for I/O event callbacks (onReceive, onClose, onError)

See Reactor for full documentation.

🧵 Threading & Concurrency

Thread

POSIX thread wrapper with core affinity, real-time priority, move semantics, non-blocking join (tryJoin), and running state query.

See Thread for full documentation.

Thread Pool

Worker pool for parallel task execution. Default worker count is based on CpuTopology (physical core count). Provides distribute() and parallelForEach() parallel algorithms.

See Thread Pool for full documentation.

CPU Topology

Runtime detector for the physical CPU layout: sockets, cores, hardware threads (SMT/HT), and NUMA nodes. Read from Linux sysfs. Used internally by ThreadPool and distribute().

See CPU Topology for full documentation.

Mutex

• Mutex — standard mutual exclusion lock
• RecursiveMutex — re-entrant locking for the same thread
• SharedMutex — inter-process synchronization via shared memory

Condition Variables

• Condition — standard condition variable
• SharedCondition — condition variable for shared memory

Semaphore

• Semaphore — counting semaphore (named and unnamed)
• SharedSemaphore — semaphore for shared memory

🔄 Lock-Free Queues & Allocator

High-performance lock-free primitives built on top of the memory backends:

• Spsc — single-producer / single-consumer queue (lowest overhead)
• Mpsc — multi-producer / single-consumer queue
• Mpmc — multi-producer / multi-consumer queue
• BasicArena — lock-free slab allocator with multiple fixed-size pools

Backed by either LocalMem (anonymous private memory) or ShmMem (POSIX shared memory). Supports blocking and non-blocking push/pop, NUMA binding, and memory locking.

See Memory, Queue, Allocator, and Backoff for full documentation.

⏱️ Timers

High-resolution timers built on Linux timerfd, integrated with the reactor:

• Monotonic::Timer — uses CLOCK_MONOTONIC, unaffected by system clock changes
• RealTime::Timer — uses CLOCK_REALTIME, follows wall-clock adjustments

Supports one-shot, absolute time-point, and periodic modes. Nanosecond precision.

See Timer for full documentation.

🗂️ Utilities

File System

File I/O helpers, path manipulation, and file status queries.

Variant

Type-safe union implementation with exception-safe operations and comparison operators.

Traits

Compile-time type utilities: parameter pack manipulation (find_index, find_element, match_t), type checking (is_unique, is_alternative, count), and constructor control (EnableDefault).

Utils

General-purpose utilities: byte order conversion, string manipulation (trim, split, replace, case-insensitive compare), benchmarking, and random generation.

OpenSSL

OpenSSL library management and RAII smart pointer wrappers.

🚨 Error Handling

Custom error handling system: error category, thread-local error state (join::lastError), integration with std::error_code, and OpenSSL error integration.

📚 API Reference

Doxygen Reference