Home

Elio

Elio is a modern C++20 coroutine-based asynchronous I/O library for Linux. It provides high-performance networking primitives with native support for TCP, HTTP/1.1, and TLS.

Features

• C++20 Coroutines: First-class coroutine support with co_await and co_return
• Structured Concurrency: Scheduler-bound task groups with lexical cancel-and-join scopes
• Multi-threaded Scheduler: Work-stealing scheduler with operation-pinned per-worker I/O contexts
• Async I/O Backends: io_uring (preferred) and epoll fallback
• Signal Handling: Coroutine-friendly signal handling via signalfd
• Synchronization Primitives: mutex, shared_mutex, semaphore, event, channel, spinlock, condition_variable
• Timers: sleep_for (with a cancellation-token overload), non-cancellable sleep_until, and yield for rescheduling
• TCP Networking: Async TCP client/server with connection management
• HTTP/1.1: Full HTTP client and server implementation
• TLS/HTTPS: OpenSSL-based TLS with ALPN and certificate verification
• RPC Framework: High-performance RPC with buffer views, checksums, and cleanup callbacks
• Hash Functions: CRC32, SHA-1, and SHA-256 with incremental hashing support
• Header-only: Use the CMake target to inherit required dependencies
• CI/CD: Automated testing with ASAN and TSAN

Requirements

• Linux (kernel 5.1+ for io_uring, or any modern Linux for epoll)
• GCC 12+ or Clang 15+ with C++20 support
• CMake 3.20+
• OpenSSL development files for the default top-level build (TLS, HTTP, and HTTP/2 are enabled by default)
• liburing (optional, for io_uring backend)

To configure without OpenSSL, disable the dependent protocol targets:

cmake -S . -B build-no-tls \
  -DELIO_ENABLE_TLS=OFF \
  -DELIO_ENABLE_HTTP=OFF \
  -DELIO_ENABLE_HTTP2=OFF

Quick Start

#include <elio/elio.hpp>

using namespace elio;

coro::task<void> hello() {
    ELIO_LOG_INFO("Hello from Elio!");
    co_return;
}

int main() {
    runtime::scheduler sched(4);
    sched.start();
    
    sched.go(hello);
    
    std::this_thread::sleep_for(std::chrono::milliseconds(100));
    sched.shutdown();
}

Why Elio?

Elio is built around a few key technical decisions:

• Header-only: No separate build step, no ABI compatibility concerns. Template-heavy coroutine code naturally suits header-only distribution. Link the CMake target so consumers inherit required dependencies such as fmt, CMake's Threads target, and enabled feature/backend libraries.
• Linux-native: Deep integration with io_uring and signalfd enables optimal performance on modern Linux kernels. epoll provides a fallback for older systems.
• Per-worker I/O: Each scheduler thread owns its I/O backend (io_uring or epoll). Submission and polling stay on that owner, and pending operations retain their worker/backend generation. This ownership does not serialize concurrent access to streams or descriptors. Cross-thread scheduling uses MPSC queues on the normal path, with a locked overflow for sustained full-queue bursts.
• Work-stealing: The Chase-Lev deque provides lock-free local operations with a global load balancing fallback. Tasks with thread affinity are respected during stealing.
• Virtual stack tracking: C++20 stackless coroutines lose stack information at suspension points. Elio's intrusive virtual stack enables production debugging via elio-pstack and GDB/LLDB extensions.

Wiki Contents

• Getting Started - Installation and first steps
• Core Concepts - Coroutines, tasks, and scheduler
• Worker Leases - Lifetime and exact-owner execution for external resources
• API Contracts - Per-interface library guarantees and caller responsibilities for audit and triage
• Fork Safety - Supported process creation boundaries and inherited-runtime restrictions
• Migrating to 0.6 - Breaking changes and upgrade checklist for 0.5.x users
• Signal Handling - Safe signal handling with signalfd
• Networking - TCP, HTTP/1.1, and connections
• HTTP Routing - Immutable connection identity and reuse compatibility
• Byte Streams - Publishing-stream composition, ownership, and lifecycle
• HTTP Streaming - Owned streaming replies, incremental receive, borrowed buffers, framing, and server-owned CONNECT tunnels over TCP or HTTPS proxies
• HTTP2 Guide - Sequential client connection reuse and lower-level HTTP/2 sessions
• TLS Configuration - TLS/SSL setup and certificate management
• Security Guidelines - Library/caller responsibility boundaries, secure configuration, and vulnerability reporting guidance
• WebSocket SSE - WebSocket and Server-Sent Events
• Batch IO and File Helpers - Batch I/O operations and file utilities
• RPC Framework - High-performance RPC with buffer views and checksums
• Hash Functions - CRC32, SHA-1, and SHA-256
• RDMA Guide - Optional RDMA-Core abstraction (header-only, bring-your-own-backend)
• Performance Tuning - Optimization and benchmarking
• Debugging - GDB/LLDB extensions and elio-pstack
• Examples - Code examples and use cases
• API Reference - Detailed API documentation

License

MIT License