Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Jul 19, 2026 · 25 revisions

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.

CI

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, sleep_until, yield with cancellation support
  • 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), eliminating I/O-related locking entirely. Cross-thread communication uses lock-free MPSC queues on the normal path, with a locked overflow only 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

License

MIT License

Clone this wiki locally