The Story of the X Project

中文版

Why This Project Exists

C++11 introduced rvalue references, and with them came move semantics — a mechanism that at first glance seems like a performance optimization (avoid copying large objects) but is actually something far more profound. Before move semantics, C++ had two ways to pass a value: copy it, or pass a pointer. Copying is safe but expensive; pointers are cheap but dangerous — nothing in the type system tells you who owns the pointed-to memory, when it will be freed, or whether it's even still valid. This is why C++ codebases are haunted by "who frees this?" and "is this pointer still alive?" — questions that don't exist in garbage-collected languages, and that C++ developers pay for with valgrind sessions, ASan runs, and late-night debugging.

// Three ways to pass a buffer to another function:

// 1. Copy — safe, but deep-copies gigabytes of video frame data.
void process_copy(std::vector<uint8_t> buf);  // caller knows buf is copied

// 2. Raw pointer — cheap, but who owns this? Who frees it?
void process_ptr(uint8_t* data, size_t len);  // caller: "is data still valid?"

// 3. Rvalue reference — cheap AND clear. "I'm done with this, it's yours."
void process_move(std::vector<uint8_t>&& buf); // caller: std::move(buf)
                                               // callee: sole owner, RAII cleanup

Traditional C++ leans on copies (too expensive for large objects) or pointers (too ambiguous for ownership). Neither encodes who holds the value into the function signature.

Move semantics bridges this gap. When you std::move a value, you're not copying bits — you're transferring ownership. The source object is left in a valid-but-unspecified state, and the destination assumes full responsibility. Combined with RAII destructors, move semantics lets you express in the type system: "I am the only one who holds this resource, and when I go out of scope, it gets cleaned up." No reference counting, no garbage collector, no manual free.

Rust took this idea and made it the foundation of the language — every value has exactly one owner, the compiler enforces borrowing rules at compile time, and you get memory safety without a runtime. C++ can't match Rust's compiler-level guarantees, but we can get surprisingly close with a library. That's where libxpp comes in: a C++11 wrapper that uses move semantics to implement Own<T> (single-owner heap allocation), Box<T>, Rc<T> / Arc<T> (shared ownership), NonNull<T> (non-null pointer abstraction), and a family of Rust-inspired types like Option<T>, Result<T, E>, and Enum<Ts...>. The goal is to make value semantics, especially move semantics, the default way you write C++ — so your code reads like "I have a value, I move it to you" rather than "here's a pointer, please don't forget to free it."

Beyond Smart Pointers

Solid value types are necessary but not sufficient. A modern language also needs a good story for asynchronous I/O. The C/C++ ecosystem has no shortage of event libraries — libevent, libev, and my personal favorite, libuv — but these are event notification libraries, not async programming frameworks. They tell you that a socket became readable, but they don't give you the experience you get in Go or Rust: writing sequential-looking code that suspends and resumes across I/O boundaries.

To go from "the event loop told me there's data" to "I wrote .await() and it just worked" requires building: a scheduler that can park and resume tasks, a mechanism to yield and be re-polled, a standard API for chaining async operations, combinators for running tasks concurrently or racing them against timeouts, integration with the event loop's I/O multiplexing, and — crucially — a way to propagate errors through the async chain without losing type information. This is the sheer amount of infrastructure that separates a raw event library from an async runtime.

A natural question: why not just use Boost.Asio? Asio is the most mature async library in the C++ ecosystem, but it was designed before C++11 was widespread. It's built on a callback chain and io_service scheduling model where the type system plays a minimal role and error handling is almost entirely error_code. Coroutine support was retrofitted with macros and templates — it wasn't designed in from the start. We wanted an async stack where type safety, move semantics, and multiple await styles are first-class citizens from day one.

The Promise<T> Abstraction

Rust's Future trait is the blueprint: an async operation is a state machine that, when polled, either returns Poll::Ready(value) or Poll::Pending and registers a waker to be called when progress can be made. The executor drives the state machine by calling poll() in a loop until the future completes.

C++ doesn't have this trait as a language feature, but it gives us the tools to build it. Our Promise<T> is a concrete template with the polling interface poll(waker) → Option<T> — it holds a type-erased node (coroutine frame, adapter, or chain), but from the user's perspective, Promise<T> is always fully typed and the compiler checks every call site.

When you call .await() on a Promise, it enters a polling loop: try poll(), and if the value isn't ready, park the current context so the event loop can make progress. Once the Promise resolves — an I/O completes, a timer fires, a channel receives — the waker fires, the polling loop un-parks, and poll() returns the value. This is the same core mechanism that powers tokio, just implemented at the library level rather than in the language runtime. The full design is documented in the Promise chapter.

How to Use It

Because everything converges on poll(), Promise<T> supports three coding styles — each equally valid, each using the same underlying machinery:

1. .await() — any C++11 compiler

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

int result = fetch_value()              // Promise<int>
    .then([](int x) { return x * 2; })
    .await();                           // runs event loop until resolved

.await() drives the event loop itself — it calls xEventLoopRun(X_RUN_ONCE) in a loop until the Promise resolves. This is the universal entry point: it works in main(), in tests, anywhere a WaitScope is active.

2. .await() + fiber — non-blocking concurrency

xpp::fiber([]() {
    auto a = http_get("/a").await();    // fiber suspends, event loop continues
    auto b = http_get("/b").await();    // resumes when a is ready
    return a + b;
}).then([](int total) {
    printf("total = %d\n", total);
});

Wrap your code in xpp::fiber() and .await() automatically becomes non-blocking. The fiber gets its own 64 KiB mmap'd stack with a guard page. When .await() needs to wait, it calls swapcontext to switch back to the event loop — the fiber freezes in place, and the thread can run other fibers or handle I/O. When the Promise resolves, the waker switches back to the fiber exactly where it left off.

This is the headline feature of libxpp: C++11, no co_await syntax, no colored functions, no compiler support needed. You get the same linear-code experience as Rust's .await or Go's goroutines, on any C++11 toolchain.

3. co_await / co_return — C++20 coroutines

xpp::Promise<int> compute() {
    int x = co_await fetch_value();
    co_return x * 2;
}

If you have a C++20 compiler, Promise<T> is directly a coroutine return type. co_await compiles into the same poll() / waker mechanism as .then() chains — no separate runtime, no Task<T> wrapper.

All three styles interoperate freely. A Promise<T> returned by .then() can be .await()'d in a fiber, a coroutine can co_await a Promise built from a callback chain, and .then() can append a callback to a Promise returned by a coroutine. The library doesn't care which style you choose — it's the same poll() underneath.

Building the Async Stack

With Promise<T> as our foundation, we can build the same async modules that Rust developers reach for:

• I/O utilities: BufReader/BufWriter for efficient buffered I/O, io::copy() and io::read_all() for common patterns, Duplex/Simplex for in-process communication
• Network: TcpStream for async TCP, TcpListener for accepting connections, UdpSocket, DNS resolution, TLS with OpenSSL or mbedTLS
• FileSystem: async File with cursor tracking, stat, directory operations
• Channels: oneshot (single-value), mpsc (bounded and unbounded), broadcast (multi-consumer with lag detection), watch (version-tracked latest value), plus Notify for bare signal coordination

We deliberately align our API with both the STL (naming conventions, iterator patterns) and Tokio (channel semantics, async method signatures, error types). A Rust developer should recognize mpsc::channel::<T>(cap); a C++ developer should find rx.recv() and tx.send(v) familiar. This dual alignment is a design constraint, not an afterthought.

The Foundation: libx

All of this runs on top of libx, a C99 library that provides the event loop, non-blocking I/O, timers, lock-free queue primitives, and (since xbase/fiber.h) cross-platform stackful fibers with xFiberCreate / xFiberSwitch. libx was built with the same philosophy: give C developers an async runtime they can start using immediately — no callback hell, no manual fd management, just xTcpConnect() and a promise-like callback. libxpp is the C++ layer that adds type safety, move semantics, .await() ergonomics, and xpp::fiber() integration on top — the name says it directly: the C core is libx, the C++ binding is libxpp.

Into the Design

If you want to dive into the details behind each piece:

• Type System — how Own<T>, Box<T>, Rc<T>, Arc<T>, and NonNull<T> implement Rust-style ownership in a library, and where the limits are compared to a compiler-enforced borrow checker.
• Promise Model — the poll-and-waker state machine, .await() semantics (fiber suspend + direct event loop drive), C++20 coroutine frame mapping, and the internals of chaining, cancellation, and error propagation.
• Async I/O — the layering from raw AsyncFd up through BufReader/BufWriter to type-safe TcpStream and File, plus utilities like io::copy and in-process Duplex/Simplex pipes.
• Channels — the full Tokio-aligned suite: oneshot, mpsc (bounded via lock-free ring buffer, unbounded via lock-free linked list), broadcast with lag recovery, watch with version-tracked "seen" semantics, and Notify as a reusable wake primitive.
• Threading Model — Arc<T> (atomic refcount) for all shared library state — the old XPP_MT switch and Shared<T> alias were removed, Rc<T> remains for explicit single-threaded use — the loom module of swappable primitives for future concurrency testing, and RAII close semantics across all channels.
• Network — async TCP, UDP, DNS, and TLS, all built on the same Promise<T> foundation.
• Filesystem — async file I/O with cursor tracking, stat, and directory operations.
• Time(TODO) — tokio-style time primitives — Instant, Duration, sleep, interval, timeout — built on Promise<T>.

The design philosophy throughout is the same: leverage what C++ gives us (move semantics, RAII, coroutine code generation) to build an async experience that feels like Rust with Tokio, still runs on a C foundation, and fits into existing C++ codebases without requiring a language fork or a custom compiler.

The result is a stack where C and C++ each get the async experience they deserve: libx for systems programmers who need raw control with structured concurrency, and libxpp for application developers who can choose between xpp::fiber([]() { auto v = promise.await(); ... }) in C++11, Promise<T>::then([](auto v){...}) for callback chains, or co_await promise for C++20 coroutines — no pointers, no leaky abstractions, no callback pyramids.

X 项目设计哲学

English

为什么要做这个项目

C++11 引入了右值引用，随之而来的是移动语义——这个机制表面上看是一个性能优化（避免拷贝大对象），但它实际上要深刻得多。在移动语义出现之前，C++ 只有两种传递值的方式：拷贝，或者传指针。拷贝是安全的但昂贵；指针廉价但危险——类型系统里没有任何东西告诉你谁拥有这块内存、它什么时候会被释放、甚至它是否还有效。这就是为什么 C++ 代码库里总是萦绕着"这该谁 free？"和"这指针还活着吗？"之类的问题——这些问题在有 GC 的语言里根本不存在，C++ 开发者只能自己承担，靠 valgrind 跑内存泄漏、靠 ASan 查越界、靠一次次调试定位悬挂指针。

// 三种把 buffer 传给另一个函数的方式：

// 1. 拷贝 — 安全，但会深拷贝上 GB 的视频帧数据。
void process_copy(std::vector<uint8_t> buf);  // 调用方知道 buf 被拷贝了

// 2. 裸指针 — 廉价，但这块内存谁持有？谁来释放？
void process_ptr(uint8_t* data, size_t len);  // 调用方："data 还有效吗？"

// 3. 右值引用 — 廉价且语义清晰。"我用完了，归你了。"
void process_move(std::vector<uint8_t>&& buf); // 调用方：std::move(buf)
                                               // 被调方：独享所有权，RAII 自动清理

传统 C++ 要么靠拷贝（大对象太贵），要么靠指针（所有权模糊）。两者都无法 在函数签名里编码"谁持有这个值"。

移动语义填补了这个鸿沟。当你对某个值 std::move 时，你并不是在拷贝字节——你是在转移所有权。源对象被留在一个"有效但未指定"的状态，而目标对象承担全部责任。配合 RAII 析构，移动语义让你可以在类型系统里表达："我是唯一持有这个资源的人，当我离开作用域时，它就会被清理。"不需要引用计数，不需要垃圾回收，不需要手动 free。

Rust 接过了这个理念并把它做成了语言的基础——每个值有且仅有一个所有者，编译器在编译期强制检查借用规则，你不需要运行时就能获得内存安全。C++ 做不到 Rust 那种编译器级别的保证，但能用库来做相当接近的事情。这就是 libxpp 的由来：一个 C++11 封装库，利用移动语义实现了 Own<T>（单所有者堆分配）、Box<T>、Rc<T> / Arc<T>（共享所有权）、NonNull<T>（非空指针抽象），以及一整套 Rust 风格的类型：Option<T>、Result<T, E>、Enum<Ts...>。目标是让值语义——特别是移动语义——成为写 C++ 的默认方式，这样代码读起来就是"我有一个值，我把它移动给你"，而不是"给你指针，别忘了释放"。

智能指针只是开始

扎实的值类型是必要的，但还不够。一门现代语言还需要一个好的异步 I/O 叙事。C/C++ 生态不缺事件库——libevent、libev，以及我个人最爱的 libuv——但这些是事件通知库，不是异步编程框架。它们告诉你某个 socket 可读了，但不给你 Go 或 Rust 那种体验：写一段看起来是顺序执行的代码，在 I/O 边界处自动挂起和恢复。

要从"事件循环告诉我来数据了"走到"我写下 .await() 它就自己跑起来了"，需要构建的东西包括：一个能挂起和恢复任务的调度器、一种让出执行权并等待被重新 poll 的机制、一套串联异步操作的标准 API、能并发执行或竞速超时的组合器、与事件循环的 I/O 多路复用的集成，以及——最关键的是——在不丢失类型信息的前提下把错误沿着异步链路传播出去的方式。这些东西，就是区分一个裸事件库和一个异步运行时的"非常多的东西"。

也许有人会问：为什么不直接用 Boost.Asio？Asio 确实是 C++ 生态里最成熟的异步库，但它的问题在于设计时 C++11 还没普及，整个库建立在一个庞大的回调链和 io_service 调度模型上，类型系统参与感很弱，错误处理几乎全靠 error_code。Coroutine 支持是后期用宏和模板"粘"上去的，而非原生设计。我们想要的是一个从头开始就把类型安全、移动语义和多种 await 方式作为一等公民来设计的异步栈。

Promise<T> 抽象

Rust 的 Future trait 是蓝图：一个异步操作就是一个状态机，被 poll 的时候要么返回 Poll::Ready(value)，要么返回 Poll::Pending 并注册一个 waker 以便在有进展时被唤醒。执行器通过循环调用 poll() 来驱动状态机，直到 future 完成。

C++ 没有这个 trait 作为语言特性，但它给了我们实现它的工具。我们的 Promise<T> 是一个具体模板，提供 poll(waker) → Option<T> 的 polling 接口——它内部持有一个类型擦除后的节点（协程帧、适配器或链），但从使用者角度看，Promise<T> 始终是完整类型的，编译器在每一个调用点都会检查。

当你对一个 Promise 调用 .await() 时，它进入一个 polling 循环：先尝试 poll()，如果值还没就绪，就 park 当前上下文让事件循环推进进度。一旦 Promise 被 resolve——某个 I/O 完成、定时器触发、channel 收到值——waker 被调用，polling 循环解除 park，poll() 返回值。这就是驱动 tokio 的核心机制，只不过我们是在库层面实现的，而不是在语言运行时里。完整设计见 Promise 章节。

如何使用

因为一切最终都收敛到 poll() 上，Promise<T> 支持三种编码风格——每种同等有效，共用同一套底层机制：

1. .await() —— 任意 C++11 编译器

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

int result = fetch_value()              // Promise<int>
    .then([](int x) { return x * 2; })
    .await();                           // 驱动事件循环直到 resolved

.await() 自己驱动事件循环——它在一个循环里调用 xEventLoopRun(X_RUN_ONCE)，直到 Promise resolve。这是最通用的入口：main() 里能用，测试里能用，任何有 WaitScope 的地方都能用。

2. .await() + fiber —— 非阻塞并发

xpp::fiber([]() {
    auto a = http_get("/a").await();    // fiber 挂起，事件循环继续
    auto b = http_get("/b").await();    // a 就绪后恢复
    return a + b;
}).then([](int total) {
    printf("total = %d\n", total);
});

把代码包进 xpp::fiber()，.await() 就自动变成非阻塞的。fiber 有自己的 64 KiB mmap 栈（带 guard page）。当 .await() 需要等待时，它调用 swapcontext 切回事件循环——fiber 原地冻结，线程可以跑其他 fiber 或处理 I/O。Promise resolve 时，waker 切回 fiber，精确地从断点继续执行。

这是 libxpp 的主打特性：C++11，不需要 co_await 语法，不需要给函数染色，不需要编译器支持。 你得到的是和 Rust .await、Go goroutine 一样的线性代码体验，用在任何 C++11 工具链上。

3. co_await / co_return —— C++20 协程

xpp::Promise<int> compute() {
    int x = co_await fetch_value();
    co_return x * 2;
}

如果你有 C++20 编译器，Promise<T> 直接就是协程返回类型。co_await 编译到同样的 poll() / waker 机制上——不需要独立的运行时，不需要 Task<T> 包装。

三种风格可以自由混用。.then() 链返回的 Promise<T> 可以在 fiber 里 .await()，协程可以 co_await 一个由回调链构建的 Promise，.then() 也可以接在协程返回的 Promise 后面。库不关心你选哪种风格——底层都是同样的 poll()。

构建异步技术栈

以 Promise<T> 为基础，我们可以构建 Rust 开发者熟悉的那套异步模块：

• I/O 工具：BufReader/BufWriter 做高效缓冲读写，io::copy() 和 io::read_all() 处理常见模式，Duplex/Simplex 做进程内通信
• 网络：TcpStream 做异步 TCP，TcpListener 接受连接，UdpSocket、DNS 解析、基于 OpenSSL 或 mbedTLS 的 TLS
• 文件系统：带游标追踪的异步 File、stat、目录操作
• Channel：oneshot（单值）、mpsc（有界和无界）、broadcast（多消费者 + 滞后检测）、watch（版本追踪的最新值），外加 Notify 做纯粹的信号通知

我们在 API 设计上刻意同时对齐 STL（命名惯例、迭代器模式）和 Tokio（channel 语义、异步方法签名、错误类型）。Rust 开发者看到 mpsc::channel<int>(cap) 应该会感到熟悉，C++ 开发者看到 rx.recv() 和 tx.send(v) 也不会有距离感。这不是一个附加的偏好，而是一个设计约束。

底层基础：libx

所有这一切都运行在 libx 之上，一个 C99 库，提供了事件循环、非阻塞 I/O、定时器、无锁 MPSC 队列，以及（自 xbase/fiber.h 起）跨平台有栈 fiber（xFiberCreate / xFiberSwitch）。libx 建基于同样的理念：给 C 开发者一个开箱即用的异步运行时——没有回调地狱，不需要手动管理 fd，只需要 xTcpConnect() 和一个 promise 式的回调。libxpp 是在此之上的 C++ 层，增加了类型安全、移动语义、.await() 易用性，以及 xpp::fiber() 集成——名字本身就是这个关系：底层 C 库叫 libx，上层 C++ 库自然就叫 libxpp。

走进设计

如果上面的内容让你想进一步了解每个模块的细节，以下是各部分的入口：

• 类型系统 — Own<T>、Box<T>、Rc<T>、Arc<T>、NonNull<T> 如何在库层面实现 Rust 风格的所有权，以及和编译器强制 borrow checker 相比的边界在哪
• Promise 模型 — poll-waker 状态机，.await() 语义（fiber 挂起 + 直接驱动事件循环），C++20 协程帧如何映射到 Promise<T>，串联、取消和错误传播的内部机制
• 异步 I/O — 从原始 AsyncFd 往上经过 BufReader/BufWriter 到类型安全的 TcpStream 和 File 的分层架构，以及 io::copy、Duplex/Simplex 等工具
• Channel — 完整的 Tokio 对齐套件：oneshot、mpsc（有界用无锁环形缓冲区，无界用无锁链表）、带滞后恢复的 broadcast、版本追踪"已读"语义的 watch，以及可复用的唤醒原语 Notify
• 线程模型 — 所有共享库状态统一使用 Arc<T>（原子引用计数）——旧的 XPP_MT 开关和 Shared<T> 别名已移除，Rc<T> 保留给显式单线程使用；loom 模块提供可替换的并发原语用于未来的并发测试，以及所有 channel 的 RAII close 语义
• Network — 异步 TCP、UDP、DNS、TLS，全部建立在同一个 Promise<T> 基础上
• Filesystem — 异步文件 I/O，带游标追踪，支持 stat、目录操作等
• Time(TODO) — Tokio 风格的时间原语 — Instant、Duration、sleep、interval、timeout — 全部基于 Promise<T>

贯穿始终的设计哲学是同一个：善用 C++ 已经给我们的东西（移动语义、RAII、协程代码生成），构建一个用起来像 Rust + Tokio 的异步体验，底层跑在 C 的基础上，能融入现有 C++ 项目而无需语言分支或自定义编译器。

最终形成的技术栈让 C 和 C++ 各自获得它们应得的异步体验：libx 给需要结构化并发的系统程序员，libxpp 给可以选用 xpp::fiber([]() { auto v = promise.await(); ... })（C++11）、Promise<T>::then([](auto v){...})（回调链）或 co_await promise（C++20 协程）的应用开发者——没有裸指针，没有泄漏的抽象，没有回调金字塔。

libxpp

C++11 bindings for libx — stackful fibers, smart pointers, async primitives, and type utilities. Header-only.

At a Glance

#include <xpp/arc.h>
#include <xpp/box.h>
#include <xpp/option.h>
#include <xpp/result.h>
#include <xpp/promise.h>
#include <xpp/fiber.h>

// .await() — THE way to wait for a Promise.  Works everywhere:
//   outside a fiber: drives xEventLoopRun directly (blocking)
//   inside a fiber:  suspends via xFiberYield (non-blocking)
int result = xpp::resolve(42)
    .then([](int x) { return x * 2; })
    .await();
// result == 84

// Coalesce many concurrent I/O calls with xpp::fiber():
xpp::fiber([]() {
    auto a = http_get("/a").await();  // fiber suspends, event loop keeps running
    auto b = http_get("/b").await();  // resumes when a is ready
    return a + b;
}).then([](int total) {
    printf("total = %d\n", total);
});

// Also supports C++20 coroutines (co_await / co_return):
#if XPP_HAS_COROUTINES
xpp::Promise<Stats> fetch() {
    auto raw = co_await http_get("/api/stats");
    co_return parse_stats(raw);
}
#endif

// Result<T, E> — explicit error handling, no exceptions
xpp::Result<int, std::string> parse(std::string_view s) {
    if (s.empty()) return xpp::err("empty input");
    return xpp::ok(std::stoi(std::string(s)));
}

// Option<T> — nullptr == None, sizeof == sizeof(T*)
xpp::Option<xpp::Arc<Config>> cached = lookup(key);
if (cached) use(**cached);

Design philosophy:

• .await() first — fiber + event loop — .await() is the canonical way to wait. Outside a fiber it drives xEventLoopRun directly. Inside a fiber (via xpp::fiber()) it suspends via xFiberYield — non-blocking, stackful, M:N concurrency without co_await syntax. C++20 coroutines are a first-class option too.
• Rust-inspired, C++11-compatible — Result/Option/Arc/Box with the same semantics as their Rust counterparts, but portable to any C++11 toolchain.
• Zero overhead — every smart pointer is sizeof(T*). Option<Arc<T>> is also sizeof(T*) via niche optimization (nullptr = None). Empty allocators vanish via EBO.
• Single allocation — Arc::make() allocates the control block and value together in one heap block, matching Rust's Arc::new.

Modules

• EventLoop & WaitScope — RAII wrappers for the libx event loop
• Fiber — Stackful coroutines via xpp::fiber() + .await()
• Promise — Composable deferred values
  • .await() & Waiting — .await() semantics (fiber + blocking), event loop integration
  • Deferred Resolution — async(), PromiseResolver, cross-thread
  • Timers & Timeouts — after(), timeout pattern
  • Combinators (all/race) — all(), race(), waker sharing
  • Utilities (try_next) — try_next(), sequential fall-through
  • Custom Adapters — adapt(), work(), Adapter contract
  • C++20 Coroutines — co_await/co_return (optional)
  • Internals — PromiseNode hierarchy, poll-based model
• Allocator — Allocator protocol, GlobalAllocator, custom allocators
• Arena — Bump allocator for short-lived objects (Arena<N>)
• Smart Pointers — Own, Box, Rc/Weak, Arc/ArcWeak, NonNull
  • Own — Nullable unique ownership
  • Box — Non-null unique ownership
  • Rc & Weak — Single-thread shared ownership
  • Arc & ArcWeak — Thread-safe shared ownership
  • NonNull — Non-owning, non-null reference
• Result — Success or error (Rust Result)
• Option — A value or nothing (Rust Option)
• String — UTF-8 string (Rust String)
• Vec — Contiguous growable array (Rust Vec)
• Enum — Type-safe tagged union
• Timer — Callback-based timer with pause/resume
• Filesystem — Async file I/O (File, stat, exists, create_dir, rename)
• I/O — Reactive async I/O for non-blocking fds (AsyncFd, read, write, Error)
• Net — Async TCP/UDP/DNS/URL/TLS (TcpStream, TcpListener, UdpSocket, lookup_host, Url, TlsContext)
• Panic — Assert macros
• Compiler Macros — Attribute/deprecation helpers
• Opaque Handle Wrapper — RAII for XDEF_HANDLE typedefs

Allocator

Introduction

libx++ smart pointers (Arc, Rc, Own, Box) accept an optional Allocator template parameter that controls how the control block (or the pointed-to object) is allocated and deallocated. The default GlobalAllocator uses ::operator new / ::operator delete and is empty (zero overhead via EBO).

The protocol is modeled after Rust's std::alloc::Allocator trait: allocate returns a fat-pointer Span<uint8_t> (pointer + actual size), deallocate takes a Layout (size + align), and grow/shrink are optional with default implementations provided.

Design Philosophy

1. Rust-style &self. allocate and deallocate are const-qualified. Stateful allocators track state via mutable members or atomic pointers — std::atomic<T>::fetch_add is itself const, so counters held by pointer work without any mutable dance. This lets callers pass const Allocator& if they only have a const reference.

2. Layout bundles size + align. Passing them as a pair avoids bugs from mismatched deallocate(ptr, size) calls where the size doesn't match the original allocation's alignment. Layout::of<T>() derives both from the type, so callers rarely construct one by hand.

3. Fat-pointer return. allocate returns Result<Span<uint8_t>, AllocError> rather than Result<void*, AllocError>. The Span carries the actual allocated size (which may be larger than requested — allocate-at-least semantics). Smart pointers ignore the slack; callers that want it (e.g. for a growable buffer) can use it.

4. Empty allocator → zero overhead. GlobalAllocator is an empty class. EBO (via inheritance for ArcInner/RcInner, via CompressedPair for Own/Box) collapses it to zero bytes, so sizeof(Arc<T>) == sizeof(T*) with the default allocator.

5. Allocator lives in the control block, not the handle. For Arc/Rc, the Allocator instance is stored inside ArcInner/RcInner — not inside the Arc/Rc handle. This keeps sizeof(Arc<T, Allocator>) == sizeof(T*) for any A, stateful or not. For Own/Box, the Allocator is stored via CompressedPair<T*, Allocator> and grows the handle when stateful (no separate control block to hide it in).

Architecture

graph TD
    subgraph "Allocator protocol"
        L["Layout { size, align }"]
        S["Span<uint8_t> { data, size }"]
        E["AllocError (empty)"]
        A["Allocator::allocate(Layout) const → Result<Span, AllocError>"]
        D["Allocator::deallocate(void*, Layout) const noexcept"]
        G["Allocator::grow / shrink (optional)"]
        A --> L
        A --> S
        A --> E
        D --> L
        G --> L
    end

    subgraph "GlobalAllocator (default)"
        GA["allocate: ::operator new(size, align)"]
        GD["deallocate: ::operator delete(ptr, size, align)"]
    end

    subgraph "Smart pointer storage"
        ARC["ArcInner<T, A> { strong, weak, value, alloc }"]
        OWN["CompressedPair<T*, A> { ptr, alloc }"]
    end

    A --> GA
    D --> GD
    A --> ARC
    A --> OWN

Layout

struct Layout {
  size_t size;
  size_t align;

  template <class T> static Layout of();        // sizeof(T), alignof(T)
  static Layout array(size_t n, size_t a);      // n bytes, a alignment
};

AllocError

AllocError is an empty struct. allocate returns Result<Span<uint8_t>, AllocError> — callers must handle the error path. (Smart pointers panic on allocation failure, matching the existing ::operator new behavior that throws std::bad_alloc.)

Span<uint8_t>

Span<uint8_t> is a non-owning fat pointer (pointer + length). The length is the actual allocated size, which may be larger than the requested layout.size. Smart pointers ignore the length; it's there for callers that want to use the slack.

GlobalAllocator

The default. Empty class → EBO-eligible → zero storage overhead in ArcInner / CompressedPair.

struct GlobalAllocator {
  Result<Span<uint8_t>, AllocError> allocate(Layout layout) const;
  void deallocate(void *ptr, Layout layout) const;
};

Uses C++17 aligned ::operator new / ::operator delete when available; falls back to non-aligned on C++11.

API Reference

Required methods

Optional methods

Default grow / shrink

Free functions that implement grow/shrink as allocate + memcpy + deallocate. Used when the allocator doesn't provide its own.

template <class A>
Result<Span<uint8_t>, AllocError> default_grow(const A &alloc, void *ptr,
                                                Layout old_l, Layout new_l);
template <class A>
Result<Span<uint8_t>, AllocError> default_shrink(const A &alloc, void *ptr,
                                                  Layout old_l, Layout new_l);

Smart pointer factory methods

make() uses SFINAE to detect whether the first argument is an Allocator instance (for stateful allocators) or a constructor argument for T. make_in() is the explicit form that always treats the first argument as the allocator — use it when SFINAE detection is ambiguous (T's first ctor arg is convertible to Allocator).

Usage Examples

Arc with default allocator

auto a = Arc<std::string>::make("hello");
// sizeof(a) == sizeof(std::string*)

Arc with stateful allocator

struct CountingAllocator {
  std::atomic<int> *allocs;
  std::atomic<int> *deallocs;

  CountingAllocator(std::atomic<int> *a, std::atomic<int> *d) : allocs(a), deallocs(d) {}

  xpp::Result<xpp::Span<uint8_t>, xpp::AllocError> allocate(xpp::Layout layout) const {
    void *p = ::operator new(layout.size);
    if (!p) return xpp::Result<xpp::Span<uint8_t>, xpp::AllocError>(xpp::err, xpp::AllocError{});
    allocs->fetch_add(1, std::memory_order_relaxed);
    return xpp::Result<xpp::Span<uint8_t>, xpp::AllocError>(
        xpp::ok, xpp::Span<uint8_t>(static_cast<uint8_t *>(p), layout.size));
  }

  void deallocate(void *ptr, xpp::Layout) const {
    deallocs->fetch_add(1, std::memory_order_relaxed);
    ::operator delete(ptr);
  }
};

std::atomic<int> allocs{0}, deallocs{0};
CountingAllocator alloc(&allocs, &deallocs);

{
  auto a = Arc<int, CountingAllocator>::make(alloc, 42);  // SFINAE: alloc detected
  EXPECT_EQ(allocs.load(), 1);
  auto b = a.clone();                                       // no new alloc — shares inner
  EXPECT_EQ(allocs.load(), 1);
}
EXPECT_EQ(deallocs.load(), 1);

Own / Box with custom allocator

struct FileAlloc {
  void deallocate(void *p, xpp::Layout) const noexcept {
    if (p) fclose(static_cast<FILE *>(p));
  }
};

xpp::Own<FILE, FileAlloc> file(fopen("data.txt", "r"), FileAlloc{});
// sizeof(file) == sizeof(FILE*)  (FileAlloc is empty → EBO)

make_in for the ambiguous case

struct Logger {
  explicit Logger(GlobalAllocator) {}  // first ctor arg convertible to Allocator
};

// make(GlobalAllocator{}) would be ambiguous — SFINAE treats it as the alloc.
// Use make_in to force the alloc interpretation:
auto a = Arc<Logger>::make_in(GlobalAllocator{}, GlobalAllocator{});
//                     ^ alloc         ^ Logger ctor arg

grow / shrink

// Default implementation (allocate + memcpy + deallocate):
auto r = xpp::default_grow(alloc, old_ptr, old_layout, new_layout);

// Custom implementation (e.g. in-place realloc):
struct ReallocAllocator {
  // ... allocate / deallocate ...

  xpp::Result<xpp::Span<uint8_t>, xpp::AllocError> grow(void *ptr, xpp::Layout old_l,
                                                          xpp::Layout new_l) const {
    void *p = ::realloc(ptr, new_l.size);
    if (!p) return xpp::default_grow(*this, ptr, old_l, new_l);
    return xpp::Result<xpp::Span<uint8_t>, xpp::AllocError>(
        xpp::ok, xpp::Span<uint8_t>(static_cast<uint8_t *>(p), new_l.size));
  }
};

Comparison

Implementation Notes

EBO (Empty Base Optimization)

When Allocator is an empty class (like GlobalAllocator), it is stored as a base class of the control block (ArcInner / RcInner) or via CompressedPair (Own / Box), not as a member. This gives zero storage overhead:

• sizeof(Arc<T, GlobalAllocator>) == sizeof(T*)
• sizeof(Own<T, GlobalAllocator>) == sizeof(T*)
• sizeof(ArcInner<T, GlobalAllocator>) == sizeof(strong) + sizeof(weak) + sizeof(T) (no Allocator byte)

When Allocator is stateful, it is stored as a member and sizeof grows by sizeof(Allocator) (rounded for alignment). The Arc/Rc/ArcWeak/Weak handles themselves stay at sizeof(T*) because the Allocator lives in the control block, not in the handle — only Own/Box grow because they have no separate control block.

EBO is gated on is_empty<A> && !is_final<A> — final classes can't be inherited from, so they fall back to member storage even when empty.

Deallocation lifecycle (Arc/Rc)

The trickiest part of the stateful-allocator path: the Allocator lives inside the control block that it's about to free. The deallocator moves the Allocator out before freeing:

// In arc_dec_weak_and_maybe_dealloc:
if (inner->weak.fetch_sub(1, std::memory_order_release) == 1) {
  std::atomic_thread_fence(std::memory_order_acquire);
  Allocator a = std::move(inner->alloc_ref());   // move out
  Layout layout = Layout::of<ArcInner<T, Allocator>>();
  a.deallocate(inner, layout);                // free the memory that contained `a`
}

Allocator must be move-constructible (enforced by static_assert in Arc/Rc). For empty allocators the move is trivial; for stateful allocators it should be noexcept (move the resource handle, not copy it). The moved-from Allocator inside inner is never accessed again — its resources are now owned by the local a, whose destructor runs after deallocate returns.

Destruction order (Own/Box)

The destructor calls ~T() explicitly, then alloc.deallocate(ptr, Layout::of<T>()) — separating object destruction from memory deallocation, matching Rust's Allocator trait. This is necessary because deallocate only frees memory; it does not call destructors.

For T = void, ~T() is skipped via tag dispatch (_::destroy_and_dealloc checks std::is_void<T>), and Layout{0, 1} is used as a sentinel — GlobalAllocator::deallocate calls ::operator delete(ptr, 0, align_val_t(1)), which is valid (size 0 is a no-op hint, the actual free still happens).

Shared helpers in allocator.h

allocator.h defines three helpers in xpp::_ shared by all smart pointers:

• IsFinal<D> — portable is_final (C++14 / __is_final intrinsic / fallback to false)
• FirstIsAlloc<Allocator, Args...> — SFINAE: true iff first arg in Args... is convertible to Allocator
• destroy_and_dealloc<T, Allocator>(ptr, alloc) — calls ~T() (if not void) then alloc.deallocate(ptr, Layout::of<T>())

Extracting these to a shared header prevents redefinition when arc.h + rc.h + box.h are included together.

Arena

Introduction

Arena<N> is a fixed-size bump allocator for short-lived objects. Memory is allocated by bumping a pointer forward; individual allocations are never freed — only bulk-freed via arena destruction or reset(). This eliminates per-object malloc/free overhead for groups of objects with the same lifetime.

The size N is a compile-time template parameter. Small arenas (N ≤ 256) store the buffer inline (zero heap allocation); large arenas heap-allocate the buffer at construction (one allocation). allocate() returns nullptr when full — the caller checks and falls back to ::operator new if needed.

Design Philosophy

1. Bump, never free individually. A bump pointer moves forward on each allocate(). There is no per-object free-list, no fragmentation, no bookkeeping. The entire arena is freed in one shot when destroyed or reset().

2. Compile-time size, automatic storage. The template parameter N determines the buffer size. ArenaStorage<N> specializes at compile time: N ≤ 256 → inline (the buffer is a member of the Arena object), N > 256 → heap (the buffer is ::operator new'd at construction). The user writes Arena<128> or Arena<4096> and the storage strategy is automatic.

3. nullptr on overflow, not auto-grow. When the arena is full, allocate() returns nullptr. The caller checks and falls back to heap. This keeps the arena simple (no chunk list, no growth logic) and makes owns() a trivial O(1) pointer range check.

4. No destructor tracking. The arena does not call ~T() — the caller is responsible for destructing objects before reset() or arena destruction. This keeps the arena zero-overhead. make<T>() constructs in-place, but the caller must call ~T() manually.

5. C++11, header-only, no dependencies. arena.h includes only <cstddef>, <cstdint>, <new>, <type_traits>, <utility>. No libx dependency.

Architecture

graph TD
    subgraph "Arena<N> (N ≤ 256, inline)"
        IA["ArenaStorage<N, true>"]
        IB["alignas(max_align_t) char buf[N]"]
        IP["m_pos → bump pointer"]
        IE["m_end → buf + N"]
        IA --> IB
        IA --> IP
        IA --> IE
    end

    subgraph "Arena<N> (N > 256, heap)"
        HA["ArenaStorage<N, false>"]
        HB["char* ptr → ::operator new(N)"]
        HP["m_pos → bump pointer"]
        HE["m_end → ptr + N"]
        HA --> HB
        HA --> HP
        HA --> HE
    end

    subgraph "allocate(size, align)"
        AL["align_up(m_pos, align)"]
        AC{"fits?"}
        AF["return p, m_pos += size"]
        AN["return nullptr"]
        AL --> AC
        AC -->|yes| AF
        AC -->|no| AN
    end

ArenaStorage specialization

Inline (N ≤ 256):                Heap (N > 256):
┌─────────────────────┐          ┌─────────────────────┐
│ ArenaStorage        │          │ ArenaStorage        │
│ ┌─────────────────┐ │          │ ┌─────────────────┐ │
│ │ buf[N]          │ │          │ │ ptr ────────────┼─┼──→ heap buffer
│ │ ████░░░░░░░░    │ │          │ └─────────────────┘ │
│ └─────────────────┘ │          │                     │
├─────────────────────┤          ├─────────────────────┤
│ m_pos, m_end        │          │ m_pos, m_end        │
└─────────────────────┘          └─────────────────────┘
sizeof = N + ~16                  sizeof = ~24
0 heap allocations                1 heap allocation

Memory layout

Arena<256> on the stack:

  [buf[0] ... buf[255]] [m_pos] [m_end]
  ↑                     ↑
  begin                 current bump position
  └─── capacity = 256 ─┘

  allocate(32):
    p = align_up(m_pos, align)
    m_pos = p + 32
    return p

  ┌──allocated──┬─── remaining ───┐
  │  ████████   │  ░░░░░░░░░░░░   │
  └─────────────┴─────────────────┘
  ↑             ↑                 ↑
  begin         m_pos             m_end

API Reference

Arena<N>

Move semantics

• Inline arenas: move copies the buffer and adjusts pointers. The moved-from arena is invalidated.
• Heap arenas: move steals the heap pointer. The moved-from arena is invalidated.
• Copy is deleted (bump allocators are not copyable).

owns() — O(1) ownership check

bool owns(const void* p) const {
    const char* cp = static_cast<const char*>(p);
    return cp >= m_storage.begin() && cp < m_end;
}

Used by dealloc paths to decide: arena-allocated → skip ::operator delete; heap-allocated → call ::operator delete.

Usage Examples

Basic bump allocation

xpp::Arena<256> arena;

void* a = arena.allocate(64);   // bump, 0 malloc
void* b = arena.allocate(32);   // bump, 0 malloc
void* c = arena.allocate(128);  // bump, 0 malloc
// remaining = 256 - 64 - 32 - 128 = 32

void* d = arena.allocate(64);   // nullptr — overflow
// Caller checks and falls back to heap:
if (!d) d = ::operator new(64);

Typed allocation with make<T>

xpp::Arena<256> arena;

auto* str = arena.make<std::string>("hello");
auto* num = arena.make<int>(42);

EXPECT_EQ(*str, "hello");
EXPECT_EQ(*num, 42);
EXPECT_TRUE(arena.owns(str));

// Caller must destruct manually (arena doesn't track):
str->~basic_string();
// num is trivially destructible, no need.

Reset for reuse

xpp::Arena<256> arena;

// Phase 1: allocate some objects
arena.make<int>(1);
arena.make<int>(2);
// used = 8 (2 × sizeof(int), assuming alignment)

// Reset — buffer stays, bump pointer goes back to start
arena.reset();
EXPECT_EQ(arena.used(), 0u);

// Phase 2: reuse the same buffer
arena.make<int>(3);  // overwrites the old memory

Overflow fallback pattern

xpp::Arena<256> arena;

template <class T, class... Args>
T* alloc_or_heap(Args&&... args) {
    T* p = arena.make<T>(std::forward<Args>(args)...);
    if (!p) {
        // Arena full — fall back to heap
        p = new T(std::forward<Args>(args)...);
    }
    return p;
}

// Deallocation: check owns() to route correctly
template <class T>
void dealloc(T* p) {
    if (arena.owns(p)) {
        p->~T();           // arena-allocated: just destruct
        // memory freed when arena is destroyed/reset
    } else {
        delete p;          // heap-allocated: destruct + free
    }
}

Large arena (heap storage)

xpp::Arena<4096> arena;  // sizeof(arena) ≈ 24 bytes
                          // 1 heap allocation for 4KB buffer

void* p = arena.allocate(2048);
EXPECT_TRUE(arena.owns(p));
EXPECT_EQ(arena.total_capacity(), 4096u);

Stack allocation (zero malloc)

void process() {
    xpp::Arena<128> arena;  // on the stack, 0 malloc
    auto* tmp = arena.make<int>(42);
    // ...
    // arena destructed on scope exit — buffer is stack memory, no free needed
}

Comparison

Implementation Notes

Inline vs heap threshold

The threshold is k_arena_inline_threshold = 256. This is chosen because:

• PromiseNode typical size: 24–48B. 256B fits 5–10 nodes — enough for a .then() chain.
• 256B inline is acceptable for stack allocation (default stack is 1–8MB).
• Larger arenas (4KB+) would waste stack space if inlined.

ArenaStorage specialization

The storage is handled by ArenaStorage<N, bool Inline>:

• ArenaStorage<N, true> (N ≤ 256): alignas(max_align_t) char buf[N] — buffer is a member.
• ArenaStorage<N, false> (N > 256): char* ptr — buffer is heap-allocated at construction, freed at destruction.

Arena<N> has identical code for both cases — it calls m_storage.begin() to get the buffer start. The storage specialization is transparent to the arena logic.

Alignment

The inline buffer is declared alignas(std::max_align_t), ensuring it can hold any type without alignment issues. allocate() calls align_up() to round the bump pointer up to the requested alignment. The alignment padding is counted in used() but not in any allocation that the caller sees.

No destructor tracking

Unlike kj::Arena, xpp::Arena does not maintain a destructor list. Rationale:

• PromiseNode has its own destroy() virtual method for arena-aware destruction.
• Adding a destructor list would add per-allocation overhead (function pointer + linked list node), defeating the purpose of a zero-overhead bump allocator.
• Callers who need destructor tracking can layer it on top (maintain their own list of objects to destruct).

Move semantics for inline arenas

Moving an inline arena is tricky: m_pos and m_end point into the old object's buf[N] member. After move, the buffer contents are copied (memcpy), and the pointers are recomputed relative to the new object's buffer:

Arena(Arena&& o) : m_storage(std::move(o.m_storage)) {
    if (N <= k_arena_inline_threshold) {
        size_t used = static_cast<size_t>(o.m_pos - (o.m_end - N));
        m_pos = m_storage.begin() + used;
        m_end = m_storage.begin() + N;
    } else {
        m_pos = o.m_pos;  // heap: pointers are absolute
        m_end = o.m_end;
    }
}

For heap arenas, the pointer is stolen (no copy needed) and the old arena is invalidated.

Smart Pointers

← libxpp

Rust-inspired smart pointers with sizeof == sizeof(T*) guarantees. All are header-only, C++11-compatible.

Overview

The XPP_MT / shared.h abstraction was removed: the library's internals (Bytes, channels, promise state) always use Arc<T> (atomic refcount). Rc<T> remains for user code that wants explicit zero-atomic-overhead single-threaded sharing.

All owning types default to GlobalAllocator and accept a custom Allocator template parameter. Empty allocators (like GlobalAllocator) incur zero storage overhead via EBO.

Key Design Choices

• Single pointer storage: sizeof == sizeof(T*) for all types. No two-word shared_ptr layout.
• Niche-optimized Option: Option<Arc<T>> and Option<Rc<T>> are also sizeof(T*) — nullptr = None.
• Non-intrusive: RcInner<T, Allocator> = { strong, weak, value, alloc } in a single heap allocation. T doesn't inherit anything.
• Rust-style refcount: weak count includes +1 for "all strongs as one weak". weak_count() subtracts this to match Rust semantics.
• Allocator protocol: Allocator parameter (default GlobalAllocator) controls allocation/deallocation. Stored in control block (Arc/Rc) or via CompressedPair (Own/Box) with EBO. See Allocator.
• Arc memory orders: relaxed for clone, release for drop, acquire fence only when count hits 0. Matches Rust libstd / triomphe / boost.

Covariant Up-cast

Rc<Derived, Allocator> → Rc<Base, Allocator> and Arc<Derived, Allocator> → Arc<Base, Allocator> work via covariant constructors (copy and move). Same Allocator required.

What xpp Has That STL Doesn't

Niche-Optimized Option<T>

The single biggest practical win. In xpp, Option<Own<T>>, Option<Box<T>>, Option<Rc<T>>, Option<Arc<T>>, and Option<NonNull<T>> all have sizeof == sizeof(T*). The None state is encoded via the null pointer — a value that normal construction never produces.

// STL: 16 bytes (8-byte pointer + bool + alignment padding)
std::optional<std::unique_ptr<int>> parent;

// xpp: 8 bytes — same size as a raw pointer
Option<Own<Node>> parent;

In tree, graph, or AST data structures where every node has an Option<parent> / Option<child>, this saves 8+ bytes per field. A million-node tree saves ~8 MB just on the parent edge alone.

Why STL can't do this: std::optional must be generic over all types, and std::unique_ptr(nullptr) is a valid (non-empty) state. xpp's smart pointers have a constructor-level invariant that null is unreachable — the type system guarantees a stored null pointer means None.

Non-Null by Default — Box<T>

STL has no equivalent. std::unique_ptr default-constructs to null, forcing null checks at every use site. Box<T> has no default constructor — if you have one, it owns a valid object. The compiler enforces this.

// STL: always defensive
void process(std::unique_ptr<Widget> w) {
  if (!w) return;          // ← who knows what the caller passed
  w->do_thing();
}

// xpp: type system gives the guarantee
void process(Box<Widget> w) {
  w->do_thing();           // ← never null, compiler-checked
}

Combined with Option<Box<T>>, you get explicit opt-in nullability at zero space cost — exactly Rust's model.

Single-Threaded Rc<T> (No Atomic Overhead)

std::shared_ptr's control block is always atomic, even when you know you're single-threaded. Every copy and destroy pays the memory barrier. xpp splits this into two types:

• Rc<T> — plain int refcount, zero atomic overhead, for event-loop or single-thread code
• Arc<T> — atomic refcount, for cross-thread sharing

In the dominant xpp use case (single-thread event loops), Rc<T> avoids all shared_ptr's atomic penalties.

Semantic Layering — Pick the Right Tool

Box<T> and NonNull<T> have no STL counterpart — they encode non-null guarantees in the type system that raw pointers and unique_ptr leave to convention.

Promise Ecosystem Integration

xpp smart pointers compose directly with Promise<T> chains — no glue code:

Promise<Own<Data>> fetch() {
  return Promise<void>::after(100).then([]() {
    return Own<Data>(new Data{42});  // Own flows through then()
  });
}

// Own → Box: take ownership, guarantee non-null downstream
auto boxed = fetch().await()
  .into_nonnull()   // Option<Box<Data>>
  .unwrap();        // Box<Data>

Single-Pointer Layout for All Types

All xpp smart pointers are sizeof(T*). Rc<T> and Arc<T> point directly to a co-located RcInner { strong, weak, T } block — single allocation, single pointer. std::shared_ptr is two pointers (object + control block), doubling stack/struct footprint.

Comparison with std

own.h — Nullable Owning Smart Pointer

Introduction

own.h provides Own<T, Allocator>, a move-only nullable owning smart pointer. It is the libxpp counterpart of std::unique_ptr<T>, with a Rust-style API surface and first-class integration with Box<T> and Option<Box<T>>.

The design bridges two worlds:

• Rust-like ownership — take() releases ownership (like Option::take), into_nonnull() converts to Option<Box<T>> for combinator usage.
• C++ RAII — reset(), release(), operator*, operator->, get(), operator bool all work as expected.

At rest, Own<T> is sizeof(T*) when using the default GlobalAllocator (empty-base optimization eliminates the allocator storage).

Design Philosophy

1. Nullable by default. Own<T> can be null — default-constructed, moved-from, or assigned nullptr. Use if (own) to check. If you need a type-level guarantee of non-null, use Box<T> directly.

2. Box<T> as the foundation. Own<T> is implemented as Option<Box<T, Allocator>>. The Box<T> type is non-null by construction; wrapping it in Option adds the null state. This means all Own<T> operations ultimately delegate to Box<T> for resource management.

3. Allocator via EBO. The default GlobalAllocator is an empty class. C++ empty-base optimization (EBO) collapses it to zero size, so sizeof(Own<T>) == sizeof(T*). Stateful allocators add their own size.

4. Covariant construction. Own<Derived, Allocator> implicitly converts to Own<Base, Allocator> (if the pointer is convertible). Same Allocator required — different Allocator types would have different CompressedPair layouts.

5. Void specialization. Own<void> stores a raw pointer without operator* or operator->. Useful for opaque handles where only reset() and get() matter. SFINAE removes the dereference operators when T = void. The destructor calls deallocate(ptr, Layout{0,1}) (no ~T() for void).

Architecture

classDiagram
    class Own {
        -OptionBox m_inner
        +Own() = default
        +Own(T* p)
        +Own(T* p, Deleter d)
        +Own(Box nn)
        +Own(OptionBox opt)
        +reset(T* p)
        +take() T*
        +release() T*
        +get() T*
        +operator*() T
        +operator->() T*
        +operator bool()
        +into_nonnull() OptionBox
    }
    class Box {
        <<non-null>>
        +from_raw(T*)
        +try_from_raw(T*) Option
        +into_raw() T*
        +operator*() T
    }
    class Option {
        +is_some() bool
        +is_none() bool
        +unwrap() T
        +take() Option
    }
    Own *-- Box : via Option
    OptionBox ..> Box

Own<T> is Option<Box<T>>. That's the whole implementation.

API Reference

Construction

Mutation

Access

Bridge to Rust-style

To access the allocator, unwrap to Box first: std::move(own).into_nonnull().unwrap().allocator(). Own itself doesn't expose allocator() because an empty Own has no inner Box and thus no allocator instance.

Usage Examples

Basic ownership

xpp::Own<Connection> conn(new Connection("localhost:8080"));
if (conn) {
    conn->send("hello");
}
// Automatically deleted when `conn` goes out of scope.

Release and re-wrap

xpp::Own<Buffer> buf = allocate();

// Hand raw pointer to a C API...
c_api_process(buf.release());  // buf is now empty

// ...re-wrap the result from C API
void* raw = c_api_get_result();
buf.reset(static_cast<Buffer*>(raw));

Custom allocator

struct FileAlloc {
  void deallocate(void *p, xpp::Layout) const noexcept {
    if (p) fclose(static_cast<FILE*>(p));
  }
};
xpp::Own<FILE, FileAlloc> file(fopen("data.txt", "r"), FileAlloc{});
// `FileAlloc::deallocate` called on destruction or reset.
// sizeof(Own<FILE, FileAlloc>) == sizeof(FILE*) + sizeof(FileAlloc) (EBO if empty)

Covariant adoption

xpp::Own<FileStream> stream = open_file_stream("data.bin");
xpp::Own<Stream>     base   = std::move(stream);  // implicit upcast (same Allocator)
base->read(buf, len);
// Own<Base> destructor calls ~FileStream() then GlobalAllocator::deallocate.

Bridge to Option<Box<T>> for combinators

xpp::Own<int> maybe_own = compute_value();

// Convert to Option<Box<int>> and use Option combinators:
auto result = std::move(maybe_own).into_nonnull()
              .map([](auto &box) { return *box * 2; })
              .unwrap_or(0);

Opaque void handles

// Own<void> has no operator* or operator-> — just get/reset/release.
xpp::Own<void> handle(platform_create_window());
platform_draw(handle.get());
// ~Own<void> calls GlobalAllocator::deallocate (which calls ::operator delete).

Comparison

Implementation Notes

Storage

template <class T, class Allocator = GlobalAllocator>
class Own {
  using Inner = Option<Box<T, Allocator>>;
  Inner m_inner;
};

Own<T> is a thin wrapper around Option<Box<T, Allocator>>. Every operation maps to a corresponding Option or Box operation:

Empty-Base Optimization

static_assert(sizeof(Own<int>) == sizeof(int*),
              "Own<T, GlobalAllocator> must be sizeof(T*)");

GlobalAllocator is stateless (empty class). The compiler applies EBO via CompressedPair, so Box<T, GlobalAllocator> has no extra storage cost beyond T*, and Option<Box<T>> (which uses aligned_storage) also collapses to sizeof(T*).

Stateful allocators (custom allocators with members) add their size on top. If the allocator itself is empty (stateless struct), EBO applies again — sizeof(Own<T, EmptyAlloc>) == sizeof(T*).

Destruction

The destructor calls ~T() explicitly, then alloc.deallocate(ptr, Layout::of<T>()) — separating object destruction from memory deallocation, matching Rust's Allocator trait. For T = void, ~T() is skipped (tag dispatch) and Layout{0, 1} is used as a sentinel.

SFINAE on operator* / operator->

template <class U = T,
          class = typename std::enable_if<!std::is_void<U>::value>::type>
U& operator*() const noexcept;

When T = void, the enable_if fails and the compiler removes the overload from the candidate set. This avoids hard errors while keeping the API clean — Own<void> simply doesn't expose dereference.

Covariance

The covariant constructor uses a friend declaration to access m_inner of another instantiation:

template <class U,
          class = typename std::enable_if<
              std::is_convertible<U*, T*>::value &&
              !std::is_same<U, T>::value>::type>
Own(Own<U, Allocator> &&other) noexcept : m_inner(std::move(other.m_inner)) {}

template <class, class> friend class Own;

Two constraints gate the conversion: pointer convertibility (Derived* → Base*) and non-identity (not Own → Own). Same Allocator required — different Allocator types would have different CompressedPair layouts. The friend declaration is necessary because Own<U, Allocator>::m_inner is private to that instantiation.

Default vs debug

operator* and operator-> only check in debug builds (XPP_DEBUG_ASSERT). This is intentional: the cost of a null check on every pointer dereference is rarely acceptable in release builds. The contract is that callers must ensure non-null via if (own) or structural proof before dereferencing — exactly the same contract as unique_ptr::operator*.

box.h — Non-Null Owning Smart Pointer

Introduction

box.h provides Box<T, Allocator>, a non-null owning smart pointer with a Rust-style API. Unlike Own<T> which is nullable, Box<T> is guaranteed non-null by construction — no default constructor, no reset(), no null state.

A partial specialization Option<Box<T, Allocator>> enables niche optimization: nullptr encodes None, so sizeof(Option<Box<T>>) == sizeof(T*) — matching Rust's Option<Box<T>>.

Design Philosophy

1. Non-null at the type level. Box<T> deletes the default constructor. Construction from a null raw pointer panics in debug. This eliminates an entire class of null-dereference bugs.

2. EBO via CompressedPair. CompressedPair<T, Allocator> uses private inheritance for empty allocators to achieve zero storage overhead — sizeof(Box<T, GlobalAllocator>) == sizeof(T*).

3. Niche optimization for Option<Box<T>>. The Option<Box<T>> specialization stores a single CompressedPair; nullptr means None. No bool tag, no wasted bytes — matches Rust exactly.

4. Covariant construction. Box<Derived, A> implicitly moves into Box<Base, A> (and Option<Box<Base, A>>) when the pointer and allocator are convertible — matching std::unique_ptr's behavior.

5. Move-only with a "husk" state. Post-move, the source holds nullptr internally. This violates the public invariant but is hidden — the only valid operation on a moved-from Box is destruction (which guards on null). This matches std::unique_ptr's post-move contract.

Architecture

graph TD
    subgraph "User API"
        BOX["Box<T, D>"]
        FROM_RAW["from_raw(p, d)"]
        TRY_FROM_RAW["try_from_raw(p, d) → Option"]
        INTO_RAW["into_raw()"]
        OPT_BOX["Option<Box<T, D>>"]
    end

    subgraph "Storage"
        CP["CompressedPair<T*, D>"]
        EBO["Empty allocator → inherit<br/>Stateful → member"]
    end

    subgraph "Related Types"
        NN["NonNull&lt;T&gt;"]
        OWN["Own&lt;T, D&gt;"]
        OPT["Option&lt;T&gt;"]
    end

    BOX --> CP
    CP --> EBO
    OPT_BOX --> CP
    BOX --> FROM_RAW
    BOX --> TRY_FROM_RAW
    BOX --> INTO_RAW
    BOX --> NN
    OPT_BOX --> OWN
    OPT_BOX --> OPT

API Reference

Box<T, Allocator>

Deleted: default ctor, copy ctor, copy assignment.

Option<Box<T, Allocator>>

Asymmetric unwrap(): const& returns T* (borrow), && returns Box<T> (consume). Combinators pass NonNull<T> to callbacks on const& and Box<T>&& on &&.

Usage Examples

Basic ownership

auto raw = new Connection("localhost:8080");
auto box = xpp::Box<Connection>::from_raw(raw);
box->send("hello");
// box.into_raw() release; or let destructor run

Checked construction (nullable source)

Connection* maybe = pool.acquire();
auto opt = xpp::Box<Connection>::try_from_raw(maybe);
opt.inspect([](auto conn) { conn->send("acquired"); });
// If maybe was null, opt is None — no panic, no UB.

Covariant move

xpp::Box<FileStream> derived = xpp::Box<FileStream>::from_raw(new FileStream);
xpp::Box<Stream>     base    = std::move(derived);  // implicit upcast

Option<Box> combinators

auto maybe_box = xpp::Box<int>::try_from_raw(raw);
auto doubled = std::move(maybe_box)
    .map([](auto nn) { return *nn * 2; })   // nn is NonNull<int>
    .unwrap_or(0);

Custom allocator

struct FreeAlloc {
    void operator()(void* p) const noexcept { free(p); }
};
void* buf = malloc(4096);
auto box = xpp::Box<void, FreeAlloc>::from_raw(
    buf, FreeAlloc{});
// sizeof(Box<void, FreeAlloc>) == sizeof(void*)  (FreeAlloc is empty → EBO)

Compile-Time Size Guarantees

static_assert(sizeof(Box<int>) == sizeof(int*));
static_assert(sizeof(Option<Box<int>>) == sizeof(int*));

Comparison

Implementation Notes

CompressedPair

Two specializations based on whether the allocator is empty and non-final:

// Empty + non-final → inherit privately (EBO)
template <class T, class D> struct CompressedPair<T, D, true> : private D {
    T* p;
};

// Stateful → store as member
template <class T, class D> struct CompressedPair<T, D, false> {
    T* p;
    D  d;
};

__is_final detection supports C++11 toolchains that lack std::is_final (C++14). On truly ancient toolchains, the check degrades to "assume not final" — a size-not-correctness issue.

Option<Box> Niche Optimization

template <class T, class Allocator>
class Option<Box<T, Allocator>> {
    CompressedPair<T, Allocator> m_storage;
};

Option<Box<T>> stores the same CompressedPair<T*, Allocator> as Box<T>. nullptr in m_storage.p represents None. Since Box guarantees non-null, nullptr is free to repurpose. No bool tag — sizeof(Option<Box<int>>) == sizeof(int*).

The asymmetric unwrap() is necessary because Box is move-only: const& cannot move out, so it returns T* (a borrow). && consumes the Option and returns Box<T> by move.

Post-move husk

After Box(Box&&) or Option<Box>(Box&&), the source's m_storage.p is set to nullptr. The destructor guards:

~Box() {
    if (m_storage.p) m_storage.allocator()(m_storage.p);
}

This allows the defaulted move operations (no custom cleanup needed for the source) while keeping size minimal.

rc.h / weak.h — Single-Threaded Reference Counting

Introduction

rc.h provides Rc<T, Allocator>, a non-null shared-owning reference-counted handle to a heap-allocated T. weak.h provides Weak<T, Allocator>, a non-owning observer that does not keep T alive. Together they form a single-threaded ownership system with explicit cycle-breaking — the same design as Rust's std::rc::Rc<T, Allocator> + std::rc::Weak<T, Allocator>.

Key properties:

Rc is co-located but NOT intrusive: T does not need to inherit from anything. A single Rc<T, Allocator>::make(args...) call allocates an RcInner<T, Allocator> block that carries the strong count, weak count, the value, and the allocator instance side by side — warm cache lines and one free when the last observer leaves. See Allocator for the allocator protocol.

Architecture

graph TD
    subgraph "Construction"
        MAKE["Rc<T>::make(args)"]
        INNER["RcInner<T> — heap (strong=1, weak=1, value)"]
        MAKE --> |"single ::operator new"| INNER
    end

    subgraph "Ownership"
        RC["Rc<T> — sizeof = T*"]
        RC2["Rc<T> (clone) — strong += 1"]
        W["Weak<T> — weak += 1"]
        INNER --> RC
        RC --> |"copy / Rc::clone"| RC2
        INNER --> W
    end

    subgraph "Drop Path"
        DROP_STRONG["Rc destroyed → strong -= 1"]
        DROP_T["strong == 0 → ~T() → weak -= 1"]
        DROP_WEAK["Weak destroyed → weak -= 1"]
        FREE["weak == 0 → ::operator delete(inner)"]
        DROP_STRONG --> DROP_T
        DROP_T --> |"weak -= 1"| FREE
        DROP_WEAK --> FREE
    end

    subgraph "Upgrade"
        UPGRADE["weak.upgrade()"]
        NONE["None (strong == 0)"]
        SOME["Some(Rc) (strong += 1)"]
        UPGRADE --> |"strong == 0"| NONE
        UPGRADE --> |"strong > 0"| SOME
    end

Reference-Count Layout (matches Rust)

strong = number of Rc<T> handles
weak   = number of Weak<T> handles + 1  (the +1 represents "the set of all live Rcs")

When the last Rc drops:

1. strong hits 0 → destroy T in place
2. Decrement weak (this is the "+1 for all strongs" unwinding)
3. If weak now hits 0 → free the inner block

This two-stage teardown means Weak::upgrade() can safely read strong even after every visible Rc is gone — the inner memory outlives T.

API Reference

Rc<T>

Rc<T> has no default constructor — it is always non-null when valid.

Weak<T>

Option<Rc<T>> Specialization

A full specialization of Option<Rc<T>> at sizeof(T*) via the niche (nullptr = None):

Usage Examples

Basic lifecycle

auto r1 = Rc<std::string>::make("hello");
EXPECT_EQ(r1.strong_count(), 1);

{
    auto r2 = r1;                    // copy — strong += 1
    EXPECT_EQ(r1.strong_count(), 2);
    EXPECT_EQ(*r2, "hello");
}                                    // r2 dropped — strong -= 1

EXPECT_EQ(r1.strong_count(), 1);

Covariant upcast

struct Base { virtual ~Base() = default; };
struct Derived : Base {};

Rc<Derived> derived = Rc<Derived>::make();
Rc<Base>    base    = derived;                    // implicit covariant copy
// Both point at the same inner, strong == 2.

Option<Rc<T>> niche

Option<Rc<int>> opt = Rc<int>::make(42);          // Some
EXPECT_TRUE(opt.is_some());

Rc<int> taken = std::move(opt).unwrap();          // Move out
EXPECT_TRUE(opt.is_none());                       // Niche preserved

static_assert(sizeof(Option<Rc<int>>) == sizeof(int*), "niche check");

Tree with cycle-free back-edges (Rc + Weak)

struct Node {
    Weak<Node>              parent;               // weak — does NOT keep parent alive
    std::vector<Rc<Node>>   children;             // strong — owns children
};

Rc<Node> root  = Rc<Node>::make();
Rc<Node> child = Rc<Node>::make();

root->children.push_back(child.clone());
child->parent = Rc<Node>::downgrade(root);        // weak += 1, strong unchanged

// Walk up:
if (auto p = child->parent.upgrade()) {
    p.unwrap()->...                               // parent still alive
}

// When root goes out of scope:
//   root's strong → 0 → T destroyed
//   root's vector destroyed → child Rc dropped
//   child's strong → 0 → T destroyed → Weak::parent dtor → weak -= 1
//   weak → 0 → inner freed
// No leak. ✓

Observer pattern

class Subject {
    std::vector<Weak<Observer>> m_observers;       // weak — doesn't own

public:
    void attach(const Rc<Observer>& obs) {
        m_observers.push_back(Weak<Observer>(obs));
    }

    void notify() {
        for (auto& w : m_observers) {
            if (auto obs = w.upgrade()) {
                obs.unwrap()->on_event();
            }
            // expired entries naturally skipped; lazy cleanup possible
        }
    }
};

Comparison

Implementation Notes

Inner block layout

template <class T, class Allocator> struct RcInner {
    size_t strong;   // number of Rc<T, Allocator> handles
    size_t weak;     // number of Weak<T, Allocator> + 1 (the +1 represents all live Rcs)
    T      value;    // co-located — warm cache
    Allocator  alloc;    // for deallocation (EBO if empty)
};

Single allocation via alloc.allocate(Layout::of<RcInner<T, Allocator>>()), zero external control block. Used by both Rc<T, Allocator> and Weak<T, Allocator> sharing the same pointer. The Allocator is stored in RcInner (not in the handle) so sizeof(Rc<T, Allocator>) == sizeof(T*) for any A. When the last weak drops, the Allocator is moved out before deallocate frees the memory.

Two-stage destruction

Rc drop path:
  rc_dec_strong(inner):
    if --strong == 0:
      inner->value.~T()                    // ① destroy T
      rc_dec_weak_and_maybe_dealloc(inner) // ② drop the "+1 for all strongs"
      
Weak drop path:
  rc_dec_weak_and_maybe_dealloc(inner):
    if --weak == 0:
      ::operator delete(inner)             // ③ free inner block

Steps ② and ③ are the same function. When no Weak ever existed, weak goes from 1→0 in the same call as ②, so the inner is freed immediately — no dangling empty block.

weak_count convention

Rc::weak_count() returns inner->weak - 1 — excludes the implicit +1. When only Rcs exist (no Weak), this reads 0, matching Rust's Rc::weak_count(). Weak::weak_count() uses the same formula when strong > 0, otherwise returns inner->weak (the +1 was already unwound when the last Rc dropped).

Option<Rc<T>> niche

The specialization stores a raw RcInner<T>* directly, with nullptr encoding None. Both Option<Rc<T>> and Rc<T> are friend class of each other so the specialization can access the private raw-pointer constructor and the unwrap() fast path avoids double-counting.

Why "Rc" not "Ref"

Ref is overloaded across C++ libraries (WebKit's WTF::Ref is intrusive; Qt's QRef is different again). The Rc spelling makes it unambiguous that this follows Rust's non-intrusive, co-located design — recognizable even without reading the header.

arc.h — Atomic Reference Counting (Thread-Safe)

Introduction

arc.h provides Arc<T, Allocator>, the thread-safe atomic counterpart of Rc<T, Allocator>. It also provides ArcWeak<T, Allocator>, a cross-thread-safe non-owning observer. Together they form the same ownership model as Rc/Weak but with std::atomic<size_t> counts and carefully chosen memory ordering — matching Rust's std::sync::Arc<T, Allocator> + std::sync::Weak<T, Allocator>.

Key properties:

Design Philosophy

1. Same shape as Rc. Arc<T> mirrors Rc<T> in API and layout. The only difference is std::atomic<size_t> instead of plain size_t, plus the atomic operations with the memory order discipline below.

2. Proven memory order. The acquire/release pattern is the same one used by Rust's libstd, triomphe, and boost::atomic_shared_ptr — battle-tested across millions of crates and deployments.

3. Fence-on-drop, not fence-everywhere. Clone uses memory_order_relaxed (no synchronisation needed for mere ownership transfer). Only the thread that actually destroys T or frees the inner pays the acquire fence cost. All other threads pay only fetch_add/fetch_sub — the cheapest atomic RMW the hardware offers.

4. CAS upgrade. ArcWeak::upgrade() uses a compare-exchange loop rather than a check-then-increment (which would race with another thread's drop). This is the canonical lock-free pattern for weak-to-strong conversion.

5. Choose Arc only when needed. If ownership never crosses threads, use Rc<T>. Arc's atomic operations are ~3–5× slower on contended cores. The type system doesn't enforce this choice — it's a documentation and review discipline.

Architecture

graph TD
    subgraph "Thread A"
        A1["Arc<T>::make()"]
        A2["Arc<T> clone — fetch_add(1, relaxed)"]
        A3["Arc<T> drop — fetch_sub(1, release)"]
    end

    subgraph "Thread B"
        B1["Arc<T> clone — fetch_add(1, relaxed)"]
        B2["Arc<T> drop — fetch_sub(1, release)"]
        B3["ArcWeak::upgrade() — CAS loop on strong"]
    end

    subgraph "Inner Block (heap)"
        I["ArcInner<T>"]
        S["strong: atomic<size_t>"]
        W["weak: atomic<size_t>"]
        V["value: T"]
        I --> S
        I --> W
        I --> V
    end

    A1 --> |"new ArcInner"| I
    A2 --> S
    A3 --> S
    B1 --> S
    B2 --> S
    B3 --> S

    subgraph "Final Drop (either thread)"
        D["strong.fetch_sub(1, release) == 1"]
        F1["atomic_thread_fence(acquire)"]
        DT["~T()"]
        DW["weak -= 1 → if 0: ::operator delete"]
        D --> F1
        F1 --> DT
        DT --> DW
    end

    A3 -.-> |"if last"| D
    B2 -.-> |"if last"| D

Memory Order Discipline

API Reference

Arc<T>

Identical API to Rc<T> — all operations are atomic under the hood.

ArcWeak<T>

Option<Arc<T>> Specialization

Same niche optimization as Option<Rc<T>>: nullptr = None, sizeof == sizeof(T*).

Usage Examples

Cross-thread ownership

auto shared = Arc<std::string>::make("hello");

std::thread t([shared]() {               // copy — strong += 1 (relaxed)
    EXPECT_EQ(*shared, "hello");
    // shared dropped here — strong -= 1 (release)
});

t.join();
EXPECT_EQ(shared.strong_count(), 1);     // only the outer handle remains

Publisher-subscriber with ArcWeak (the canonical use)

struct Subscriber {
    virtual void on_event(const std::string&) = 0;
};

class Publisher {
    std::mutex                     m_lock;
    std::vector<ArcWeak<Subscriber>> m_subs;

public:
    void subscribe(const Arc<Subscriber>& s) {
        std::lock_guard lk(m_lock);
        m_subs.push_back(Arc<Subscriber>::downgrade(s));
    }

    void publish(const std::string& event) {
        std::lock_guard lk(m_lock);
        auto write = m_subs.begin();
        for (auto& w : m_subs) {
            if (auto s = w.upgrade()) {
                s.unwrap()->on_event(event);     // safe — own a strong ref
                *write++ = std::move(w);
            }
            // else: subscriber already dropped — skip and compact
        }
        m_subs.erase(write, m_subs.end());
    }
};

ArcWeak::upgrade races correctly

// Thread A                               // Thread B
auto s = Arc<int>::make(42);              
auto w = Arc<int>::downgrade(s);
                                          // last Arc drops here:
                                          //   strong goes 1→0 → ~T()
                                          //   inner stays (weak > 0)
auto opt = w.upgrade();                   
// opt is None ✓ — the CAS saw strong==0 before bumping
// No use-after-free because the inner block is still live

Niche-optimized Option

static_assert(sizeof(Option<Arc<int>>) == sizeof(int*));

Option<Arc<int>> opt = Arc<int>::make(42);
Arc<int> taken = std::move(opt).unwrap();          // move out, no double-count
EXPECT_TRUE(opt.is_none());

Comparison

Implementation Notes

ArcInner layout

template <class T, class Allocator, bool UseEbo = /* is_empty<Allocator> && !is_final */>
struct ArcInner {
    std::atomic<size_t> strong;
    std::atomic<size_t> weak;
    T                   value;
    Allocator               alloc;     // non-EBO: stored as member
};

template <class T, class Allocator>
struct ArcInner<T, Allocator, /* UseEbo = */ true> : private Allocator {
    std::atomic<size_t> strong;
    std::atomic<size_t> weak;
    T                   value;     // EBO: Allocator inherited as base, 0 bytes
};

Same co-located design as RcInner<T, Allocator>, but with std::atomic<size_t> for the two counts. The value field itself is not atomic — it is only accessed while the caller holds an Arc<T>, which guarantees strong >= 1 for the duration of the access.

The Allocator is stored in ArcInner (not in the Arc handle) so sizeof(Arc<T, Allocator>) == sizeof(T*) for any A. When the last weak drops, the Allocator is moved out before deallocate frees the memory that contained it — required for stateful allocators that hold resources. See Allocator for details.

Why relaxed clone is correct

When thread A clones an Arc and sends it to thread B via a channel (or any synchronized handoff), the channel itself provides the happens-before — not the clone's fetch_add. The relaxed increment is therefore safe: no thread reads T until it has received the Arc through a properly synchronized channel, at which point the channel's release/acquire pair (or mutex unlock/lock) has already established visibility of all prior writes to T.

The only thread that needs acquire on the count is the one that destroys T — because it must see writes from every prior owner, and those writes were released via the counter's fetch_sub(release) on drop, not via any external channel.

CAS in upgrade()

Option<Arc<T>> upgrade() const noexcept {
    if (!m_inner) return Option<Arc<T>>();
    size_t s = m_inner->strong.load(relaxed);
    for (;;) {
        if (s == 0) return Option<Arc<T>>();
        if (m_inner->strong.compare_exchange_weak(s, s+1, acquire, relaxed)) {
            // ...construct Some(Arc) directly...
        }
    }
}

The CAS loop is necessary because between the load and the increment, another thread may drop the last Arc. A naive if (strong > 0) ++strong would bump 0→1 and resurrect a destroyed T. The CAS ensures the increment is conditional on strong still being the value we read.

Shared inner, separate Rc/Arc

Rc<T> and Arc<T> use different inner types (RcInner<T> vs ArcInner<T>) and different decrement helpers (rc_dec_strong vs arc_dec_strong). The two systems are completely separate — you cannot construct a Weak<T> from an Arc<T>, and you cannot upgrade an ArcWeak<T> into an Rc<T>. This is deliberate: mixing thread-safe and non-thread-safe counts on the same block is unsound.

Sized asserts

static_assert(sizeof(Arc<int>)           == sizeof(int*));
static_assert(sizeof(Option<Arc<int>>)    == sizeof(int*));
static_assert(sizeof(ArcWeak<int>)        == sizeof(int*));

All three collapsed to a single pointer — no hidden allocations, no control block indirection.

nonnull.h — Non-Null Pointer Wrapper

Introduction

nonnull.h provides NonNull<T>, a guaranteed-non-null pointer wrapper with a niche-optimized Option<NonNull<T>> specialization. It is the libxpp counterpart of Rust's NonNull<T> and Option<&T> niche optimization.

sizeof(NonNull<T>) == sizeof(T*) and sizeof(Option<NonNull<T>>) == sizeof(T*) — matching Rust's layout exactly. Compared to Option<T*> (16 bytes due to the bool tag), this saves 8 bytes per slot when non-nullness can be proven at the type level.

Why Not Just T*?

A raw T* has no type-level non-null guarantee. Passing T* everywhere forces every caller to either document or check the "must not be null" contract. NonNull<T> moves the contract into the type system:

API Reference

NonNull<T>

Copyable, moveable, trivially destructible.

Option<NonNull<T>>

Usage Examples

Binding to a reference

int x = 42;
xpp::NonNull<int> p(x);   // Always safe — references are non-null
*p = 10;                    // modifies x

Checked construction from raw pointer

int* raw = get_some_pointer_maybe_null();
auto opt = xpp::NonNull<int>::from(raw);
opt.inspect([](auto p) { *p += 1; });

Type-level contract in APIs

// Before: "widget must not be null" (documentation contract)
void draw(Widget* widget);

// After: contract enforced at compile time
void draw(xpp::NonNull<Widget> widget);

Niche-optimized Option

struct Node {
    int value;
    xpp::Option<xpp::NonNull<Node>> next;  // 8 bytes, not 16
    // nullptr = None, any other = Some
};
static_assert(sizeof(Node) == 16);  // int (4+padding) + pointer (8)

Combinator chain

auto result = xpp::NonNull<Connection>::from(raw)
    .map([](auto conn) { conn->send("ping"); return conn->recv(); })
    .unwrap_or("timeout");

Implementation Notes

Storage

template <class T>
class NonNull {
    T* m_ptr;   // Invariant: m_ptr != nullptr
};

Just a raw pointer with an invariant. No runtime overhead beyond what T* already costs. Option<NonNull<T>> stores T* directly — nullptr encodes None.

Reference constructor SFINAE guards

template <class U = T,
          class = typename std::enable_if<
              !std::is_void<U>::value &&
              std::is_same<U, T>::value>::type>
explicit NonNull(U& ref) noexcept : m_ptr(&ref) {}

Two constraints:

1. !std::is_void<U> — void& is ill-formed, so the constructor is removed for NonNull<void>.
2. std::is_same<U, T> — prevents GCC from preferring this template over the implicit copy constructor when a NonNull<T> lvalue is passed by value.

Niche optimization: Option<NonNull<T>>

template <class T>
class Option<NonNull<T>> {
    T* m_ptr;   // nullptr = None, non-null = Some
};

Unlike the general Option<T> which uses aligned_storage + bool (16 bytes for pointers), this specialization stores only the pointer. nullptr is a niche value — NonNull guarantees m_ptr != nullptr, so nullptr is free to repurpose.

static_assert(sizeof(Option<NonNull<int>>) == sizeof(int*));

The same pattern is used by Option<Box<T>> (box.h) and Rust's Option<Box<T>> / Option<NonNull<T>> in the standard library.

result.h — Value or Error

Introduction

result.h provides Result<T, E>, a type that holds exactly one of: a success value T or an error E. It is the libxpp counterpart of Rust's Result and C++23's std::expected.

No empty state. A Result is always either Ok or Err. Accessing the wrong variant panics. The tag dispatch ok(value) / err(e) mirrors Rust's Ok(x) / Err(e) idiom for ergonomic construction.

A partial specialization Result<void, E> handles operations that succeed with no value (only an error can be produced).

Design Philosophy

1. Always holds something. No default constructor, no null state. A Result must be initialized with Ok or Err.

2. Three unwrap trust levels. unwrap() always checks (release too), unwrap_unchecked() only in debug, operator*() / operator->() never check — identical to Option's pattern.

3. Combinators mirror Rust. map, map_err, and_then, or_else, unwrap_or_else, inspect, inspect_err, transpose — all with the same semantics and rvalue-qualified consuming overloads.

4. Void success via specialization. Result<void, E> avoids the OkSentinel dance: a zero-size tag type marks the Ok variant, operator* and operator-> are removed, and combinators accept zero-arg functions.

5. Option <-> Result bridge. Option::ok_or(e) → Result<T, E>, Result::ok() → Option<T>, Result::err() → Option<E>, Result::transpose() → Option<Result<U, E>> when T = Option<U>.

Architecture

graph TD
    subgraph "User API"
        OK["ok(value) → OkResult<T>"]
        ERR["err(e) → ErrResult<E>"]
        RESULT["Result<T, E>"]
        VOID_R["Result<void, E>"]
    end

    subgraph "Type System"
        ENUM["Enum<T, E>"]
        OPTION["Option<T>"]
        IS_OPT["is_option<T> trait"]
    end

    subgraph "Combinators"
        MAP["map(fn) → Result<U, E>"]
        MAP_ERR["map_err(fn) → Result<T, F>"]
        AND_THEN["and_then(fn) → Result<U, E>"]
        OR_ELSE["or_else(fn) → Result<T, F>"]
        TRANSPOSE["transpose() → Option<Result<U, E>>"]
        INSPECT["inspect / inspect_err"]
        OK_OR["ok() / err() → Option"]
    end

    OK --> RESULT
    ERR --> RESULT
    RESULT --> ENUM
    RESULT --> MAP
    RESULT --> MAP_ERR
    RESULT --> AND_THEN
    RESULT --> OR_ELSE
    RESULT --> TRANSPOSE
    TRANSPOSE --> IS_OPT
    OK_OR --> OPTION
    VOID_R -.->|specialization| RESULT

API Reference

Tags and Factory Functions

Observers

Unwrap (checked)

Unwrap (unchecked — debug assert only)

Convenience

Combinators

Conversion to Option

Result<void, E> Members

Usage Examples

Basic Ok / Err

xpp::Result<int, std::string> r(xpp::ok, 42);
if (r.is_ok()) {
    int val = r.unwrap();  // 42
}

xpp::Result<int, std::string> fail(xpp::err, std::string("not found"));
// fail.unwrap();  // panics: "unwrap() on Err Result"

ok() / err() factory functions

auto r = xpp::ok(42);   // carrier, converts to Result<T, E>
auto e = xpp::err("nope");

xpp::Result<int, const char*> success = xpp::ok(42);
xpp::Result<int, const char*> failure = xpp::err("nope");

map + and_then chains

auto result = parse_number("42")
    .map([](int x) { return x * 2; })          // 42 → 84
    .and_then([](int x) {
        if (x > 100) return xpp::ok(x / 2);    // 84 → 42
        return xpp::err("too small");           // short-circuit
    });

map_err and or_else

auto result = load_config()
    .map_err([](auto e) { return "config error: " + e; })  // enrich error
    .or_else([](auto e) {
        log_error(e);
        return load_default_config();  // fallback
    });

Void result (operation with no value)

xpp::Result<void, xErrno> write_result = write_to_file(path, data);
if (write_result.is_ok()) {
    // success — no unwrap() needed
} else {
    xErrno e = write_result.unwrap_err();
}

// Chain: only proceed if write succeeded
write_result
    .and_then([] { return flush_file(); })
    .inspect_err([](xErrno e) { log("write failed: %d", e); });

Transpose: swap Result<Option, E>

// lookup() returns Option<int> wrapped in Result: Result<Option<int>, E>
auto found = xpp::ok(xpp::some(42));  // Result<Option<int>, E>
auto transposed = std::move(found).transpose();  // Option<Result<int, E>>
// transposed == some(Ok(42))

auto not_found = xpp::ok(xpp::Option<int>(xpp::none));
auto transposed2 = std::move(not_found).transpose();
// transposed2 == None (no error, just no value)

Comparison

Implementation Notes

Storage: Enum<T, E>

template <class T, typename E>
class Result {
    Enum<T, E> m_data;
};

Result delegates all storage and destruction to Enum<T, E>. The Ok variant is index 0, Err is index 1. is_ok() is m_data.index() == 0.

Void Specialization

template <class E>
class Result<void, E> {
    Enum<OkSentinel, E> m_data;
};

OkSentinel is a zero-size tag struct. The Enum<OkSentinel, E> stores OkSentinel at index 0 and E at index 1 — no storage overhead for the success case. is_ok() checks m_data.is<OkSentinel>() (index 0), is_err() checks m_data.is<E>() (index 1).

Option Bridge: ok_or / ok_or_else

The definitions live in result.h (not option.h) because they depend on Result<T, E> being complete:

template <class T> template <class E>
Result<T, E> Option<T>::ok_or(E e) && {
    return m_has_value ? Result<T, E>(ok, std::move(unwrap_unchecked()))
                      : Result<T, E>(err, std::move(e));
}

Option forward-declares Result, and the out-of-line definitions after Result's class body link the two. This avoids a circular header dependency.

option.h — Nullable Values with Combinators

Introduction

option.h provides Option<T>, a type-safe alternative to nullable pointers and std::optional. It closely mirrors Rust's Option<T> — both the owning Option<T> (heap-allocated or value-semantic) and the non-owning Option<T&> (zero-overhead nullable reference) — with the full set of monadic combinators.

Two key design rules separate it from std::optional:

• No implicit conversion to bool. Use is_some() / is_none() or if (o) for explicit checking.
• Abort on unwrap of None. unwrap() always checks, even in release builds. unwrap_unchecked() skips the check but debug-asserts. There is no "undefined value" path — either you handle None, or you crash cleanly.

Design Philosophy

1. Storage is placement-new, not union. The value lives in std::aligned_storage<sizeof(T), alignof(T)> with explicit construction/destruction. This avoids the limitations of C++11's restricted union support and works uniformly for non-default-constructible, non-copyable, and non-movable types (with appropriate usage).

2. Three unwrap strategies for three trust levels.

   • unwrap() — always checks. Use when the invariant is not locally obvious.
   • expect(msg) — always checks with a custom panic message. Use when the failure reason is domain-specific.
   • unwrap_unchecked() — debug-asserts only, zero-cost in release. Use when the caller has proven is_some() structurally (e.g. after if (o)).

3. Combinators are consuming where Rust is consuming. filter(), ok_or(), ok_or_else(), and unwrap_or_else() are rvalue-qualified (&&), matching Rust's self semantics. This prevents accidental use-after-move and makes ownership transfer explicit in the type system.

4. Option<T&> is a first-class specialization. sizeof(Option<T&>) == sizeof(T*). It's rebindable (unlike real C++ references), supports most combinators, and replaces raw T* with "might be null" semantics everywhere.

5. Bridge to Result. ok_or(err) and ok_or_else(fn) convert Option<T> → Result<T, E>, enabling smooth transitions between "value might be missing" and "value or error" code paths.

Architecture

classDiagram
    class Option {
        -bool m_has_value
        -aligned_storage m_storage
        +is_some() bool
        +is_none() bool
        +unwrap() T
        +unwrap_unchecked() T
        +expect(msg) T
        +unwrap_or(fallback) T
        +take() Option
        +map(fn) Option
        +and_then(fn) Option
        +or_else(fn) Option
        +unwrap_or_else(fn) T
        +filter(pred) Option
        +inspect(fn) Option
        +ok_or(err) Result
        +ok_or_else(fn) Result
    }
    class None {
        <<tag>>
    }
    class Some {
        <<factory>>
    }
    Option ..> None : "constructed from"
    Option ..> Some : "constructed via"

The two variants at a glance:

API Reference

Construction

Observers

Unwrap

Combinators

Option<T&> Specifics

• No unwrap_or_else — returning a reference to a stack local would dangle.
• No ok_or / ok_or_else — Result does not have a reference specialization.
• filter is const-qualified (not rvalue-only) — references are trivially copyable.
• take() returns Option<T&> pointing to the same object; original is cleared.

Usage Examples

Basic value presence

xpp::Option<int> maybe = get_value();

if (maybe) {
    process(maybe.unwrap());
} else {
    use_default();
}

// Or with combinators:
auto result = maybe.map([](int x) { return x * 2; })
                   .unwrap_or(0);

Short-circuit with and_then

xpp::Option<User>  user  = find_user(id);
xpp::Option<Order> order = user.and_then([](User &u) {
    return u.last_order();
});

// Only runs if user was Some AND last_order() was Some.

Fallback chain with or_else

auto config = read_file("local.conf")
              .or_else([] { return read_file("global.conf"); })
              .or_else([] { return read_file("/etc/defaults.conf"); });

Lazy default with unwrap_or_else

// compute_default() is only called if `maybe` is None.
int value = std::move(maybe).unwrap_or_else([] { return compute_default(); });

Side-effect inspection in a chain

auto result = parse(input)
              .inspect([](auto &v) { log("parsed: {}", v); })  // log if Some
              .map([](auto v) { return transform(v); });

Filter with predicate

auto positive = std::move(maybe).filter([](int x) { return x > 0; });
// positive is None if maybe was None OR value <= 0.

Nullable references (no heap, no copy)

// Find returns Option<T&> — zero allocation, pointer-sized.
auto found = registry.find(key);
if (found) {
    found.unwrap().update();  // mutates the registry entry directly
}

// Rebindable:
int a = 1, b = 2;
Option<int&> ref(a);
ref = Option<int&>(b);  // now points to b
ref.unwrap() = 99;      // b becomes 99, a unchanged

Bridge to Result

auto r = std::move(maybe_user).ok_or<std::string>("user not found");
// Result<User, string>: Ok(user) or Err("user not found")

// Lazy error:
auto r2 = std::move(maybe).ok_or_else([&] {
    return format_error("missing key: {}", key);
});

Comparison

Implementation Notes

Storage

bool m_has_value = false;
typename std::aligned_storage<sizeof(T), alignof(T)>::type m_storage;

The value is constructed in-place via new (&m_storage) T(...) and destroyed via reinterpret_cast<T*>(&m_storage)->~T(). clear() is the sole destruction site, used by destructor, assignment, and operator=(none).

aligned_storage was chosen over anonymous union to support non-default-constructible types (T() = delete) in C++11 without compiler-specific extensions.

Option<T&>

Trivially a T* pointer. is_none() is m_ptr == nullptr. No heap, no lifetime management — the caller must ensure the referent outlives the Option. Rebindable via operator=, unlike native C++ references.

Combinators on rvalue vs lvalue

Consuming combinators (filter, ok_or, ok_or_else, unwrap_or_else) are &&-qualified. This enforces Rust-like ownership semantics: you move the Option, the combinator consumes it, and the original is left in a valid-but-unspecified state (typically empty). Non-consuming combinators (map, and_then, or_else, inspect) have const& and && overloads.

Bridge to Result

ok_or and ok_or_else are declared but not defined in option.h. Their definitions live in result.h via an explicit include order dependency: the user must #include <xpp/result.h> after #include <xpp/option.h>. This avoids a circular header dependency while still allowing Option to name Result via a forward declaration.

string.h — UTF-8 String

Introduction

string.h provides xpp::String, a heap-allocated UTF-8 string backed by Vec<uint8_t>. It guarantees valid UTF-8 at the type level — const String& means "valid Unicode text", while Vec<uint8_t> means "opaque bytes".

Key differences from std::string:

• Validated UTF-8. Construction validates; mutation preserves the invariant. from_utf8() returns Result on invalid input.
• Code point iteration. chars() yields char32_t, decoding multi-byte sequences transparently.
• Dual OOM API. push() asserts on OOM; try_push_str() returns Result<void, AllocError>.
• Option returns. pop() returns Option<char32_t> — no UB on empty strings.
• Vec<uint8_t> storage. Shares the same allocator protocol as Vec<T>, enabling split_off(), retain(), shrink_to_fit(), and try_reserve().

Design Philosophy

1. Valid UTF-8 is a type-level invariant. The constructor validates; push(), insert(), and pop() preserve it. There is no way to get invalid bytes into a String without from_utf8_unchecked() (which is call-by-call UB).

2. Byte storage, code point interface. Internally Vec<uint8_t>, externally char32_t. The type system enforces the boundary — as_bytes() gives raw bytes, chars() gives decoded code points.

3. Substring on code point boundaries. substr(), truncate(), split_off(), insert(), and remove() assert that offsets land on code point boundaries — never slicing a multi-byte character in half.

4. No Unicode tables in L0. Validation, encoding, and decoding use tiny state machines (~50 lines total). Normalization, case folding, and grapheme clusters belong in a future libxpp-ext/unicode extension.

5. C++11, header-only. No <string> dependency — Vec<uint8_t> replaces std::vector<uint8_t>. No requires, consteval, or if constexpr.

Architecture

classDiagram
    class String {
        -Vec~uint8_t~ m_bytes
        +from_utf8(Vec~uint8_t~) Result~String, Utf8Error~
        +from_utf8(const char*) Result~String, Utf8Error~
        +from_utf8_unchecked(Vec~uint8_t~) String
        +as_bytes() Span~const uint8_t~
        +into_bytes() Vec~uint8_t~
        +len() size_t
        +char_len() size_t
        +empty() bool
        +chars() Chars
        +push(char32_t) void
        +push_str(String) void
        +try_push_str(String) Result
        +pop() Option~char32_t~
        +substr(size_t, size_t) String
        +find(String) Option~size_t~
        +contains(String) bool
        +starts_with(String) bool
        +ends_with(String) bool
        +insert(size_t, char32_t) void
        +insert_str(size_t, String) void
        +remove(size_t) char32_t
        +truncate(size_t) void
        +clear() void
        +split_off(size_t) String
        +replace(String, String) String
        +replacen(String, String, size_t) String
        +repeat(size_t) String
        +trim() String
        +retain(Pred) void
        +operator==(String) bool
        +operator<(String) bool
    }
    class Chars {
        +operator*() char32_t
        +operator++() Chars&
        +count() size_t
        +begin() Chars
        +end() Chars
    }
    class Utf8Error {
        +error_pos() size_t
        +into_bytes() Vec~uint8_t~
    }
    String --> Chars : "chars() creates"
    String --> Utf8Error : "from_utf8() may return"
    String *-- "1" Vec~uint8_t~ : "m_bytes"

API Reference

Construction

Views

Length / Capacity

Element Access

Mutation

Search

Utility

Comparison

Usage Examples

Construction and validation

// From a C-string — copies and validates
auto r = String::from_utf8("hello世界");
if (r.is_ok()) {
    String s = r.unwrap();
    fmt::print("len={} chars={}\n", s.len(), s.char_len());
    // → len=11 chars=7
}

// From raw bytes — validates, returns error on failure
Vec<uint8_t> bytes = read_from_network();
auto r2 = String::from_utf8(std::move(bytes));

// Unchecked — caller guarantees validity
Vec<uint8_t> data = ...;
String s = String::from_utf8_unchecked(std::move(data));

Code point iteration

String s = String::from_utf8("a你🎉").unwrap();

for (char32_t cp : s.chars()) {
    fmt::print("U+{:04X}\n", static_cast<uint32_t>(cp));
}
// → U+0061, U+4F60, U+1F389

// Manual loop
auto it = s.chars();
auto end = it.end();
while (it != end) {
    char32_t cp = *it;
    ++it;
}

Push and pop

String s;
s.push('a');
s.push(0x4F60);  // 你
s.push(0x1F389); // 🎉

auto last = s.pop();  // Option<char32_t>: Some(🎉)
s.push_str(" world");

Substring and split

String s = String::from_utf8("你好世界").unwrap();

// "你好" = first 6 bytes (你=3, 好=3)
String first_two = s.substr(0, 6);  // "你好"

// Split at character boundary
String tail = s.split_off(6);
// s    == "你好"
// tail == "世界"

Search

String s = String::from_utf8("hello xpp world").unwrap();

auto pos = s.find(String::from_utf8("xpp").unwrap());
// pos == Some(6)

if (s.contains("xpp")) { ... }
if (s.starts_with("hello")) { ... }
if (s.ends_with("world")) { ... }

Filter with retain

String s = String::from_utf8("a1b2c3").unwrap();

// Keep only ASCII letters
s.retain([](char32_t cp) { return cp >= 'a' && cp <= 'z'; });
// s == "abc"

Comparison

Implementation Notes

Validation

Single-pass scan with a ~50 line state machine. Checks:

• Continuation bytes must be 10xxxxxx
• Overlong encodings (e.g. U+002F encoded as 2 bytes)
• Surrogate halves (U+D800–U+DFFF)
• Beyond U+10FFFF

No lookup tables. No dependencies beyond <cstdint>.

Delegating to Vec

Since internal storage is Vec<uint8_t>, capacity methods are one-liner delegations:

size_t String::len()       const noexcept { return m_bytes.len(); }
size_t String::capacity()  const noexcept { return m_bytes.capacity(); }
void   String::clear()                   { m_bytes.clear(); }
void   String::reserve(size_t n)         { m_bytes.reserve(n); }

split_off() delegates to Vec::split_off() with a code point boundary check. try_reserve() and try_shrink_to_fit() delegate directly.

Chars iterator

Chars is a forward input iterator. begin() returns a copy of the current position; end() returns a sentinel with m_pos == m_end. Range-for support via instance begin()/end() — no static sentinel needed.

bytes_eq helper

Comparisons use a private bytes_eq() loop instead of memcmp() to avoid macOS C++11 C library compatibility issues.

No <string> dependency

The header does not include <string>. into_std_string() is omitted — users who need std::string can construct one from as_bytes():

String s = ...;
std::string ss(reinterpret_cast<const char*>(s.as_bytes().data()), s.len());

enum.h — Tagged Union

Introduction

enum.h provides Enum<Types...>, a type-safe tagged union holding exactly one of the specified types. It is the C++11 replacement for std::variant (C++17), serving as the storage foundation for Result<T, E>.

Always holds a value — no empty/default state. The active alternative is tracked by a runtime size_t index. Accessing the wrong alternative panics.

API Reference

Construction

Observers

Access (checked — panics on mismatch)

Access (unchecked — debug assert only)

Usage Examples

Basic usage

xpp::Enum<int, float, std::string> v(42);
assert(v.is<int>());
assert(v.index() == 0);

int x = v.get<int>();  // 42
// v.get<float>();     // panics: holding int, not float

Disambiguating duplicate types

xpp::Enum<int, int> a(xpp::InPlaceIndex<0>{}, 42);  // first int
xpp::Enum<int, int> b(xpp::InPlaceIndex<1>{}, 99);  // second int

assert(a.get<0>() == 42);
assert(b.get<1>() == 99);

In-place construction

xpp::Enum<int, std::string> v(
    xpp::InPlaceIndex<1>{}, "hello world");
assert(v.get<std::string>() == "hello world");

Unchecked access on hot paths

if (v.is<int>()) {
    // Caller has verified — skip the redundant check
    process(v.template get_unchecked<int>());
}

Comparison

Implementation Notes

Storage

template <class... Types>
class Enum {
    using Storage = typename std::aligned_union<0, Types...>::type;
    Storage m_storage;
    size_t  m_index;
};

std::aligned_union provides a byte buffer sized and aligned for the largest type in Types.... The m_index field tracks which alternative is alive.

Type-to-index mapping

template <size_t I, class T, class First, class... Rest>
struct TypeIndex<I, T, First, Rest...> {
    static constexpr size_t k_value =
        std::is_same<T, First>::value ? I : TypeIndex<I + 1, T, Rest...>::k_value;
};

Compile-time recursive template: finds the position of T in Types.... When T appears multiple times, get<T>() returns the first match.

Visit by index (internal)

Copy, move, and destroy use a compile-time visitor dispatch (VisitByIndex) that maps the runtime m_index to a typed operation:

template <class Tuple, size_t N>
struct VisitByIndex {
    template <class Fn, class Storage>
    static void run(size_t i, Storage &storage, Fn &&fn) {
        if (i == N - 1) {
            using T = typename std::tuple_element<N - 1, Tuple>::type;
            fn(reinterpret_cast<T*>(&storage));
            return;
        }
        VisitByIndex<Tuple, N - 1>::run(i, storage, fn);
    }
};

This is a linear scan (O(N)) that beats std::visit for small N (2–4 types, which covers all current use cases: Result<T, E> and Result<void, E>). For larger variants, a jump table would be faster, but libxpp doesn't need one.

Exception safety

Copy assignment uses copy-and-swap:

Enum& operator=(const Enum &o) {
    if (this != &o) {
        Enum tmp(o);     // Copy first (may throw)
        destroy();          // Only then destroy old value
        m_index = tmp.m_index;
        move_from(std::move(tmp));  // Move tmp's value in
    }
    return *this;
}

If copy_from throws, *this is left unchanged. If it succeeds, the destroy-move sequence is noexcept for moveable types, providing the strong exception-safety guarantee.

vec.h — Contiguous Growable Array

Introduction

vec.h provides Vec<T, Alloc>, a heap-allocated contiguous growable array. It replaces std::vector<T> in all xpp-owned code paths and closely mirrors Rust's std::vec::Vec in both API design and ownership semantics.

Key differences from std::vector:

• Dual API for every growth path. push() / reserve() / resize() assert on OOM; try_push() / try_reserve() / try_resize() return Result<void, AllocError> for explicit error handling.
• first() / last() return Option<T&>. No undefined behavior on empty containers — None is a first-class answer.
• pop() returns Option<T>. Moving the last element out, not just destroying it. The value is consumed, not lost.
• Allocator-aware. Accepts an optional Alloc template parameter using xpp's allocator protocol (allocate / deallocate / grow / shrink). EBO via CompressedPair means sizeof(Vec<T, GlobalAllocator>) = 24 bytes (3 words).

Design Philosophy

1. Explicit OOM, no exceptions. Every growth path has two forms: a convenience form that XPP_ASSERTs on failure (push, reserve, resize, shrink_to_fit, append), and an explicit try_* form that returns Result<void, AllocError>. Callers choose their trust level — crash-fast in debug, or handle gracefully in production paths.

2. Option for nullable access. get(i), first(), last(), and pop() all return Option. The type system encodes the possibility of "nothing there" without runtime assertions or undefined behavior. operator[] remains unchecked (debug-assert only) for hot-loop performance, use get() when index validity is uncertain.

3. Growth: double, minimum 4. On push-without-capacity, the buffer grows by max(capacity * 2, 4). The minimum ensures small Vecs don't thrash on reallocation (0 → 4 → 8 → 16 → ...). Growth uses default_grow() (allocate + memcpy + deallocate) which the allocator may override with an in-place realloc.

4. Move semantics with cleanup. Move constructor and move assignment steal the buffer and leave the source in a valid empty state (ptr = nullptr, len = 0, cap = 0). The moved-from Vec is safely destructible and reusable.

5. C++11 compatible, header-only. No requires, consteval, or if constexpr. Template parameter defaults and CompressedPair enable zero-overhead allocator storage without C++17 features.

Architecture

classDiagram
    class Vec {
        -CompressedPair~RawStorage, Alloc~ m_data
        +Vec()
        +Vec(size_t capacity, Alloc alloc)
        +Vec(const Vec&)
        +Vec(Vec&&)
        +~Vec()
        +push(T) void
        +try_push(T) Result
        +push_unchecked(T) void
        +pop() Option~T~
        +clear() void
        +truncate(size_t) void
        +get(size_t) Option~T&~
        +first() Option~T&~
        +last() Option~T&~
        +operator[]() T&
        +reserve(size_t) void
        +try_reserve(size_t) Result
        +shrink_to_fit() void
        +try_shrink_to_fit() Result
        +resize(size_t, T) void
        +try_resize(size_t, T) Result
        +append(Vec&) void
        +try_append(Vec&) Result
        +split_off(size_t) Vec
        +swap_remove(size_t) T
        +retain(Pred) void
        +begin() T*
        +end() T*
        +as_span() Span~T~
        +data() T*
        +len() size_t
        +capacity() size_t
        +empty() bool
    }
    class RawStorage {
        +T* ptr
        +size_t len
        +size_t cap
    }
    class CompressedPair {
        +first() RawStorage&
        +second() Alloc&
    }
    class Alloc {
        <<template param>>
        +allocate(Layout) Result~Span, AllocError~
        +deallocate(void*, Layout) void
        +grow / shrink (optional)
    }
    Vec *-- CompressedPair
    CompressedPair *-- RawStorage
    CompressedPair *-- Alloc

The buffer at a glance:

┌──────────────────────┬──────────────────────────────┐
│     initialized      │       uninitialized          │
│     [0 .. len)       │     [len .. capacity)        │
├──────────────────────┼──────────────────────────────┤
│ T, T, T, T, T        │ ????????????????????????????  │
└──────────────────────┴──────────────────────────────┘
        ptr                                              ptr + capacity

Elements in [0, len) are live objects with properly constructed T values. Elements in [len, capacity) are raw uninitialized memory — no constructors have run, no destructors will run. push() placement-news into the gap; pop() destructs the last element and decrements len.

API Reference

Construction

Capacity

Element Access

Mutation

Bulk Operations

Iteration

Iterators are raw pointers — compatible with C++11 range-for and STL algorithms.

Allocator Access

Usage Examples

Basic push / pop

xpp::Vec<int> v;
v.push(42);
v.push(7);
v.push(99);

// Access
int a = v[0];                    // 42
auto first = v.first();          // Option<int&>: Some(42)
auto last  = v.last();           // Option<int&>: Some(99)
auto oob   = v.get(100);         // Option<int&>: None

// Pop
auto x = v.pop();                // Option<int>: Some(99)
// v is now {42, 7}

Empty container safety

xpp::Vec<int> empty;
assert(empty.pop().is_none());   // None, not UB
assert(empty.first().is_none()); // None, not UB
assert(empty.last().is_none());  // None, not UB
assert(empty.get(0).is_none());  // None, not UB

Explicit error handling

xpp::Vec<LargeObject> v;
auto r = v.try_push(LargeObject{...});
if (r.is_err()) {
    // OOM — degrade gracefully
    return xpp::err(AllocError{});
}

Reserve + unchecked push (hot path)

xpp::Vec<int> v;
v.reserve(1000);  // one allocation
for (int i = 0; i < 1000; i++) {
    v.push_unchecked(i);  // no capacity check, no grow
}

split_off

xpp::Vec<int> v;
v.push(1); v.push(2); v.push(3); v.push(4);

auto tail = v.split_off(2);
// v    == {1, 2}
// tail == {3, 4}

swap_remove (fast unordered removal)

xpp::Vec<std::string> v;
v.push("a"); v.push("b"); v.push("c");

auto removed = v.swap_remove(0);  // removes "a", swaps "c" to position 0
// v == {"c", "b"}   (order not preserved!)

retain (in-place filter)

xpp::Vec<int> v;
v.push(1); v.push(2); v.push(3); v.push(4);

v.retain([](int x) { return x % 2 == 0; });
// v == {2, 4}

Range-for iteration

xpp::Vec<int> v;
v.push(1); v.push(2); v.push(3);

for (auto& x : v) {
    x *= 2;
}
// v == {2, 4, 6}

// Const iteration:
const auto& cv = v;
for (const auto& x : cv) {
    printf("%d\n", x);
}

Copy and move

xpp::Vec<int> a;
a.push(1); a.push(2);

xpp::Vec<int> b(a);              // deep copy
xpp::Vec<int> c(std::move(a));   // move: a is now empty, c owns the buffer

a = b;                            // copy assignment
a = std::move(b);                 // move assignment

Custom allocator

struct CountingAlloc {
    size_t allocs = 0;
    size_t frees  = 0;

    xpp::Result<xpp::Span<uint8_t>, xpp::AllocError>
    allocate(xpp::Layout layout) const {
        void* p = ::operator new(layout.size);
        if (!p) return xpp::err(xpp::AllocError{});
        const_cast<CountingAlloc*>(this)->allocs++;
        return xpp::ok(xpp::Span<uint8_t>(static_cast<uint8_t*>(p), layout.size));
    }

    void deallocate(void* ptr, xpp::Layout) const noexcept {
        const_cast<CountingAlloc*>(this)->frees++;
        ::operator delete(ptr);
    }
};

CountingAlloc ca;
{
    xpp::Vec<int, CountingAlloc> v(ca);
    v.push(1);
    v.push(2);
    assert(v.allocator().allocs >= 1);
}
// ca.frees reflects deallocation

Comparison

Implementation Notes

Storage: CompressedPair

template <class T, class Alloc>
class Vec {
    _::CompressedPair<RawStorage, Alloc> m_data;

    struct RawStorage {
        T*     ptr;   // heap buffer
        size_t len;   // initialized elements
        size_t cap;   // allocated slots
    };
};

CompressedPair applies EBO: when Alloc is empty (like GlobalAllocator), m_data is exactly RawStorage (24 bytes). When Alloc is stateful, it grows by sizeof(Alloc).

Accessor methods for CompressedPair fields

Rather than storing m_len and m_cap as reference members (which would bloat sizeof(Vec)), the implementation uses private accessor methods that return references into m_data.first():

size_t& len_() { return m_data.first().len; }
size_t& cap_() { return m_data.first().cap; }

These are inlined by the compiler — zero runtime cost, clean sizeof.

Growth: default_grow and default_shrink

grow_to() delegates to default_grow(allocator, ptr, old_layout, new_layout), which is:

1. Allocate new buffer (allocator.allocate(new_layout))
2. memcpy old elements to new buffer
3. Deallocate old buffer (allocator.deallocate(ptr, old_layout))

try_shrink_to_fit() uses default_shrink() instead of grow_to() because grow_to() short-circuits when new_cap <= capacity() — which is always true for a shrink operation. default_shrink() unconditionally reallocates to the smaller size.

For allocators with native realloc (e.g. jemalloc, tcmalloc), overriding grow() and shrink() avoids the intermediate copy.

Placement-new construction and explicit destruction

All element construction uses placement-new:

::new (ptr() + len()) T(value);   // push
::new (ptr() + len()) T(std::move(value));  // push (rvalue)

Destruction is explicit (never delete):

ptr()[i].~T();   // individual
destroy_range(begin_idx, end_idx);  // batch

dealloc_buffer() calls allocator.deallocate() on the raw memory — it does NOT call destructors. The caller must have already destroyed all live elements.

No const T

A static_assert(!std::is_const<T>::value, ...) prevents Vec<const int> — a vector of immutable elements is semantically nonsensical (you can't move out of const, can't grow by copying const, etc.).

Omitted methods

• into_raw_parts() / from_raw_parts() — data() + len() + capacity() already expose the same information. The consuming/reconstruction semantics add no capability in C++ (no FFI boundary to cross).
• first_mut() / last_mut() — C++ distinguishes mutable vs const access via const-qualification on the member function, not via separate method names.
• get_many_mut([i, j]) — Requires compile-time proof that the two indices are distinct. C++ cannot express this safely without runtime checks.

Serde

← libxpp

Introduction

xpp::serde is a trait-based serialization framework modeled on Rust's serde. A data type specializes Serialize<T> / Deserialize<T> once, and any backend that satisfies the Serializer / Deserializer concept can drive it. Backends are duck-typed (no vtable) and template-monomorphized per call site.

Why not just call to_json() / from_json() on each type?

• Every format (JSON, binary, TOML, ...) would need its own pair of methods per type — N types × M formats = N×M hand-written conversions.
• Serde inverts this: each type implements one pair of traits, each format implements one pair of backends, and the two meet at the call site. N types + M formats instead of N×M.
• The same XPP_SERDE(Person, (name)(age)) macro works for JSON, binary, and any future backend — zero edits to user types when adding a format.

Two backends ship in-tree:

• xpp::serde::json — wraps libx/x/json/ (DOM-based, human-readable)
• xpp::serde::bin — compact length-prefixed binary format

Quick Start

#include <xpp/serde/json.h>
#include <xpp/serde/serde.h>
#include <xpp/string.h>

struct Person {
  xpp::String name;
  int32_t     age;
};

// One macro generates both Serialize<Person> and Deserialize<Person>.
XPP_SERDE(Person, (name), (age))

int main() {
  Person p{"Alice", 30};

  // Serialize to JSON (one-step: mirrors serde_json::to_string)
  auto j = xpp::serde::json::to_string(p);
  xpp::String json = std::move(j).unwrap();
  // json == R"({"name":"Alice","age":30})"

  // Deserialize back
  auto d_res = xpp::serde::json::Deserializer::from_string(json);
  auto d = std::move(d_res).unwrap();
  auto r = xpp::serde::deserialize<Person>(d);
  if (r.is_ok()) {
    Person &back = r.unwrap();
    // back.name == "Alice", back.age == 30
  } else {
    xpp::serde::Error &e = r.unwrap_err();
    // e.kind, e.message
  }
}

Switching to binary is one line at the call site — Person and the XPP_SERDE macro stay untouched:

#include <xpp/serde/bin.h>

xpp::serde::bin::Serializer ser;
xpp::serde::serialize(p, ser);
xpp::Vec<uint8_t> bytes = ser.into_buffer();

auto d = xpp::serde::bin::Deserializer::from_bytes(bytes).unwrap();
auto r = xpp::serde::deserialize<Person>(d);

Trait Model

namespace xpp::serde {

template <class T> struct Serialize;     // user specializes
template <class T> struct Deserialize;   // user specializes

template <class T, class S>
Result<Void, Error> serialize(const T&, S&);        // dispatcher

template <class T, class D>
Result<T, Error>    deserialize(D&);                 // dispatcher
}

• Serialize<T>::run(const T&, S&) writes T through S&.
• Deserialize<T>::run(D&) reads a T from D&.
• Both return Result<T, Error> — no exceptions, no RTTI.
• Call sites use serde::serialize(v, ser) / serde::deserialize<T>(d), not the trait directly.

Built-in specializations: bool, int32_t, int64_t, uint32_t, uint64_t, float, double, xpp::String, Option<T>, Vec<T>.

Hand-writing a specialization

The XPP_SERDE macro covers the 80% case, but understanding the hand-written form is useful for custom logic (validation, computed fields, third-party types). The canonical example:

struct Person {
  xpp::String name;
  int32_t     age = 0;
};

namespace xpp::serde {

template <>
struct Serialize<Person> {
  template <class S>
  static Result<Void, Error> run(const Person &p, S &s) {
    // 1. Open a struct scope with the type name and field count.
    XPP_SERDE_TRY_VAR(scope, s.serialize_struct("Person", 2));
    // 2. Emit each field by key. serde::serialize dispatches to the
    //    field type's own Serialize specialization.
    XPP_SERDE_TRY(scope.field("name", p.name));
    XPP_SERDE_TRY(scope.field("age", p.age));
    // 3. Close the scope.
    return scope.end();
  }
};

template <>
struct Deserialize<Person> {
  template <class D>
  static Result<Person, Error> run(D &d) {
    struct Visitor {
      Result<Person, Error> visit_map(typename D::MapAccess &m) {
        Person p{};
        bool   got_name = false, got_age = false;
        while (true) {
          XPP_SERDE_TRY_VAR(key, m.next_key());
          if (key.is_none()) break;  // end of map
          const xpp::String &k = key.unwrap();
          if (k == "name") {
            XPP_SERDE_TRY_VAR(v, m.template next_value<xpp::String>());
            p.name = std::move(v); got_name = true;
          } else if (k == "age") {
            XPP_SERDE_TRY_VAR(v, m.template next_value<int32_t>());
            p.age = v; got_age = true;
          } else {
            // Unknown field — skip its value. Forward-compatible.
            XPP_SERDE_TRY(m.next_value_ignored());
          }
        }
        if (!got_name) return err(error(ErrorKind::MissingField, "missing 'name'"));
        if (!got_age)  return err(error(ErrorKind::MissingField, "missing 'age'"));
        return ok(std::move(p));
      }
    };
    static const char *const kFields[] = {"name", "age"};
    return d.deserialize_struct("Person", kFields, 2, Visitor{});
  }
};

} // namespace serde
} // namespace xpp

Key points:

• XPP_SERDE_TRY(expr) propagates the error from expr if it's Err. XPP_SERDE_TRY_VAR(name, expr) also captures the Ok value.
• The Visitor struct's visit_map receives a MapAccess& — call next_key() (returns Option<String>, None at end) and next_value<T>() (returns Result<T, Error>).
• Unknown fields are skipped by default — forward-compatible. Call next_value_ignored() to advance the cursor without parsing.
• Missing required fields produce Err(Error{ErrorKind::MissingField, ...}).

Nested types

Serialize<T> dispatches recursively, so nesting "just works" — no special syntax. A field of type Person inside another struct calls Serialize<Person>::run when emitted:

struct Team {
  xpp::String  team_name;
  Person       lead;
  Vec<Person>  members;
};
XPP_SERDE(Team, (team_name), (lead), (members))

Serializes to:

{
  "team_name": "infra",
  "lead": {"name": "Alice", "age": 30},
  "members": [
    {"name": "Bob", "age": 25},
    {"name": "Carol", "age": 28}
  ]
}

Option<T> serializes as null (JSON) or a discriminator tag (binary) when None; Vec<T> serializes as an array (JSON) or length-prefixed sequence (binary). Both round-trip automatically — no macro config needed.

The XPP_SERDE Macro

The macro generates the same Serialize<T> / Deserialize<T> specializations shown above, mechanically. Each field is paren-wrapped, comma-separated. Max 64 fields.

XPP_SERDE(Type, (field1), (field2), ..., (fieldN))

Field Attributes

Three attributes compose inline in the field list:

struct Config {
  xpp::String host;
  int32_t     port;
  int32_t     retries;
  xpp::String api_key;
  xpp::String internal_id;
};
XPP_SERDE(Config,
  (host),
  (port,        XPP_FIELD_DEFAULT(port, 8080)),
  (retries,     XPP_FIELD_DEFAULT(retries, 3)),
  (api_key,     XPP_FIELD_RENAME(api_key, "apiKey")),
  (internal_id, XPP_FIELD_SKIP(internal_id)))

Serializing Config{"localhost", 0, 0, "sk_123", "i_456"} produces:

{"host":"localhost","port":0,"retries":0,"apiKey":"sk_123"}

Note: internal_id is absent (SKIP), api_key is emitted as apiKey (RENAME), and port/retries use their actual values on serialize (DEFAULT only fills in on deserialize when the field is missing).

Tagged Variants (Enums)

Sum types — where a value is one of several alternatives, distinguished by a tag — use Enum<Ts...> plus XPP_ENUM_SERDE. This covers LSP messages, webhook payloads, GraphQL responses, and any protocol with a type discriminator.

struct ShapeCircle   { double r; };
struct ShapeSquare   { double s; };
struct ShapeTriangle { double base; double height; };

// Each alternative needs its own Serialize/Deserialize too.
XPP_SERDE(ShapeCircle,   (r))
XPP_SERDE(ShapeSquare,   (s))
XPP_SERDE(ShapeTriangle, (base), (height))

using Shape = xpp::Enum<ShapeCircle, ShapeSquare, ShapeTriangle>;

XPP_ENUM_SERDE(Shape,
  (ShapeCircle,   "circle"),
  (ShapeSquare,   "square"),
  (ShapeTriangle, "triangle"))

Strategies

External example:

Shape c = ShapeCircle{1.0};
// JSON: {"circle":{"r":1.0}}
// Binary: [u32 tag_index=0][f64 1.0]

Adjacent example — useful for Stripe-style {"type":"...", "data":{...}}:

using AdjShape = xpp::Enum<ShapeCircle, ShapeSquare>;
XPP_ENUM_SERDE_ADJACENT(AdjShape, "tag", "content",
  (ShapeCircle, "circle"),
  (ShapeSquare, "square"))

// JSON: {"tag":"circle","content":{"r":1.0}}

Internal tagging ({"type":"circle","r":1.0} — tag and payload fields flat in the same object) is just adjacent with the payload fields inlined directly. Use XPP_ENUM_SERDE_ADJACENT with the appropriate tag_field name.

Unknown tags on deserialize produce Err(Error{ErrorKind::UnknownField, ...}).

Backends

• JSON — wraps libx/x/json/, DOM-based, human-readable
• Binary — compact length-prefixed little-endian format

Error Model

enum class ErrorKind {
  Unexpected,      // backend-specific unexpected state
  Eof,             // ran out of input
  InvalidValue,    // type mismatch, bad UTF-8, NaN/Inf, etc.
  MissingField,    // required struct field absent on deserialize
  UnknownField,    // unknown variant tag (not unknown struct field — those are skipped)
  Custom,          // user-thrown via Error::custom
};

struct Error {
  ErrorKind kind;
  xpp::String message;
};

All fallible operations return Result<T, Error>. Construct errors with xpp::serde::error(kind, "message") or Error::custom("message"). Check r.is_ok() / r.unwrap_err().kind at the call site — no exceptions cross the serde boundary.

Common error scenarios:

C++11 Compatibility

The framework compiles on -std=c++11 with -fno-exceptions -fno-rtti. No use of if constexpr, fold expressions, structured bindings, std::variant, std::optional, std::string_view, or CTAD.

Files

JSON Backend

← serde

Introduction

xpp::serde::json::Serializer and json::Deserializer wrap libx/x/json/, providing a DOM-based JSON backend for the serde framework. The Serializer builds an xJson tree with xJsonNew* (malloc-backed) and dumps it via xJsonStringify. The Deserializer parses with xJsonParseCopy (arena-backed, safe) and walks the DOM.

Link target: any TU including json.h must link xjson.

Usage

Serialize

One-step (preferred for simple cases — mirrors serde_json::to_string):

#include <xpp/serde/json.h>

Person p{"Alice", 30};

auto r = xpp::serde::json::to_string(p);
if (r.is_ok()) {
  xpp::String json = std::move(r).unwrap();
  // json == R"({"name":"Alice","age":30})"
}

Two-step (when you need to inspect or reuse the Serializer):

xpp::serde::json::Serializer ser;
xpp::serde::serialize(p, ser);
xpp::String json = ser.to_string();

Serializer::to_string() stringifies the internal xJson tree to a compact JSON string. Call it after serialize() returns Ok. Serializer::reset() clears the internal state for reuse.

Deserialize

auto d_res = xpp::serde::json::Deserializer::from_string(R"({"name":"Bob","age":25})");
if (!d_res.is_ok()) {
  // Parse error (malformed JSON)
  xpp::serde::Error &e = d_res.unwrap_err();
  // e.kind == ErrorKind::InvalidValue, e.message has details
  return;
}
auto d = std::move(d_res).unwrap();

auto r = xpp::serde::deserialize<Person>(d);
if (r.is_ok()) {
  Person &p = r.unwrap();
  // p.name == "Bob", p.age == 25
} else {
  xpp::serde::Error &e = r.unwrap_err();
  // e.g. MissingField, InvalidValue
}

Entry points:

Both parse a copy into an arena — the input does not need to outlive the Deserializer.

Encoding

JSON is self-describing — field names are encoded as object keys, and Option<T> uses null for None. No special discriminator bytes are needed for Some; serialize_some is a plain forward to serde::serialize.

Primitives

Composite types

Example — a struct with Option and Vec:

struct Group {
  xpp::String       name;
  Option<int32_t>   priority;   // null if not set
  Vec<xpp::String>  tags;
};
XPP_SERDE(Group, (name), (priority), (tags))

Group{"infra", none, Vec<String>{"a","b"}} serializes to:

{"name":"infra","priority":null,"tags":["a","b"]}

Tagged variants

See the serde README for the macro declarations.

Unknown Fields

The JSON deserializer skips unknown fields by default — if the JSON object contains keys that the Deserialize<T> visitor doesn't recognize, they are ignored via next_value_ignored(). This makes the format forward-compatible: adding a field to the JSON (e.g. from a newer server) does not break older clients.

If you need strict mode (reject unknown fields), hand-write the Deserialize<T> specialization and return Err from the else branch instead of calling next_value_ignored().

Error Handling

All errors surface as Result<T, Error>. Common JSON-specific failures:

Errors are non-fatal — the Deserializer can be reused after an error on a different input (call from_string again).

Binary Backend

← serde

Introduction

xpp::serde::bin::Serializer and bin::Deserializer provide a compact length-prefixed binary backend. Field names are not encoded on the wire — structs are field values back-to-back. All multi-byte integers are little-endian.

This format is not self-describing — both ends must agree on the schema (field types and order). It is roughly 2-4x smaller than JSON for typical structs and faster to parse (no string comparisons for field names).

Usage

Serialize

#include <xpp/serde/bin.h>
#include <xpp/serde/serde.h>

Person p{"Alice", 30};

xpp::serde::bin::Serializer ser;
xpp::serde::serialize(p, ser);
xpp::Vec<uint8_t> bytes = ser.into_buffer();
// bytes contains the compact binary encoding

into_buffer() moves the internal buffer out (the Serializer is left empty). buffer() returns a Span<const uint8_t> borrow instead — use this when you need to inspect the bytes without taking ownership.

reset() clears the internal state for reuse.

Deserialize

auto d_res = xpp::serde::bin::Deserializer::from_bytes(bytes);
if (!d_res.is_ok()) {
  // Should not happen for a valid Vec<uint8_t>, but check anyway
  return;
}
auto d = std::move(d_res).unwrap();

auto r = xpp::serde::deserialize<Person>(d);
if (r.is_ok()) {
  Person &p = r.unwrap();
  // p.name == "Alice", p.age == 30
} else {
  xpp::serde::Error &e = r.unwrap_err();
  // e.g. Eof (truncated input), InvalidValue (bad UTF-8)
}

Entry points:

The Deserializer holds its own copy by default (safe). borrow is the zero-copy escape hatch for hot paths — the caller must ensure the source buffer outlives the Deserializer.

Wire Format

Self-delimiting for fixed-width primitives, Option, and Vec. Structs rely on the visitor knowing the field count (passed via deserialize_struct's n parameter) — there are no length prefixes or field separators between struct fields.

Example encoding

struct Point { int32_t x; int32_t y; };
XPP_SERDE(Point, (x), (y))

Point{42, -7} encodes to 8 bytes:

2a 00 00 00   f9 ff ff ff
└─ x = 42 ─┘  └─ y = -7 ─┘

For comparison, the JSON encoding is {"x":42,"y":-7} — 15 bytes, nearly 2x larger.

Schema Evolution

Because field names are not on the wire, schema changes require care:

For forward-compatible binary protocols, version the format explicitly: prefix the payload with a u32 version and dispatch on it in the Deserialize<T> specialization. Alternatively, use XPP_FIELD_SKIP on the sender side to omit new fields — but both ends must agree on which fields are skipped.

Cross-Backend Interop

The same Serialize<T> / Deserialize<T> specialization works for both JSON and binary. You can serialize to JSON, deserialize from JSON, then re-serialize to binary (or vice versa) with no code changes:

// JSON -> Person -> binary
auto jd = json::Deserializer::from_string(json_str).unwrap();
Person p = serde::deserialize<Person>(jd).unwrap();

bin::Serializer ser;
serde::serialize(p, ser);
Vec<uint8_t> bytes = ser.into_buffer();

This is useful for transcoding at protocol boundaries (e.g. receive JSON from an HTTP API, store as binary in a cache).

Error Handling

Binary-specific failures:

Unlike JSON, there is no "unknown field" concept — the reader consumes exactly the fields it expects, in order. Extra trailing bytes are silently ignored (the Deserializer stops at the last field, not at end of buffer).

Handle

Introduction

handle.h provides a single type alias:

template <class Allocator>
using OwnedHandle = Own<void, Allocator>;

libx's opaque handles are all typedef void* xFoo (via XDEF_HANDLE). Wrapping them with Own<void, Allocator> is correct but exposes void at every use site. OwnedHandle hides void behind a name that communicates intent: "I own a handle pointer."

Usage

struct EventLoopDestroy {
    void deallocate(void* h, xpp::Layout) const noexcept {
        xEventLoopDestroy(static_cast<xEventLoop>(h));
    }
};

class EventLoop {
    OwnedHandle<EventLoopDestroy> m_loop;
    // Equivalent to: Own<void, EventLoopDestroy> m_loop;
};

The allocator only needs a deallocate(void*, Layout) method — allocate is never called because handles come from the C API (e.g. xEventLoopCreate), not from the allocator. It typically casts to the correct handle type and calls the corresponding xXxxDestroy function. EBO applies — if the allocator is stateless, sizeof(OwnedHandle<Allocator>) == sizeof(void*).

Shared

compiler.h — Portable Compiler Attributes

Introduction

compiler.h wraps non-portable compiler extensions (__builtin_*, __attribute__, __declspec) behind XPP_-prefixed macros that degrade gracefully on unsupported toolchains. Self-contained — no project dependencies.

Macros

Branch Prediction

Function Attributes

Control Flow

Deprecation

Feature Detection

Usage

// Cold path: assertion failure
if (XPP_UNLIKELY(!ptr)) {
    log_error_and_abort();
}

// Intentional switch fallthrough
case STATE_A:
    init_a();
    XPP_FALLTHROUGH;
case STATE_B:
    process();

// Feature-gated coroutine support
#if XPP_HAS_COROUTINES
    // C++20 coroutine code
#endif

Implementation Notes

XPP_DEBUG defaults to !defined(NDEBUG) but is overridable at the command line. This allows enabling debug assertions in release builds (-DXPP_DEBUG=1) or disabling them in debug builds (-DXPP_DEBUG=0) for benchmarking.

XPP_HAS_COROUTINES checks both __cpp_coroutines and __cpp_impl_coroutine — Apple Clang historically defined only the latter.

panic.h — Fatal Error Reporting

Introduction

panic.h provides macros for reporting unrecoverable contract violations. Three levels of assertion:

Panics are for bugs, not runtime conditions. For recoverable errors, use Result<T, E>.

API Reference

XPP_PANIC

XPP_PANIC("invariant X violated");
XPP_PANIC("idx %zu out of range (size=%zu)", idx, size);

Outputs panic at <file>:<line>: <message> and terminates the process. The format suffix — (U+2014 em dash) separates the standard prefix from the user message.

XPP_ASSERT

XPP_ASSERT(ptr != nullptr, "null pointer passed to %s", func_name);
XPP_ASSERT(idx < size, "idx=%zu size=%zu", idx, size);

Output: panic at foo.cpp:42: assertion failed: idx < size — idx=7 size=4

The condition is always evaluated, even in release builds. The stringified condition is automatically included in the panic message.

XPP_DEBUG_ASSERT

XPP_DEBUG_ASSERT(m_has_value, "internal: Option storage uninitialized");
XPP_DEBUG_ASSERT(idx < size, "idx=%zu size=%zu", idx, size);

Compiled to ((void)0) when XPP_DEBUG=0. Used for *Unchecked() APIs (e.g. unwrap_unchecked) and internal invariants.

XPP_DEBUG

Controlled by NDEBUG:

• NDEBUG not defined → XPP_DEBUG = 1 (Debug build)
• NDEBUG defined → XPP_DEBUG = 0 (Release build)

Override with -DXPP_DEBUG=1 or -DXPP_DEBUG=0 to decouple from build type.

Usage Pattern

// Public API: always check — caller might misuse
T& Option<T>::unwrap() & {
    XPP_ASSERT(m_has_value, "unwrap() on None Option");
    return *reinterpret_cast<T*>(&m_storage);
}

// Internal hot path: debug check only — caller has verified
T& Option<T>::unwrap_unchecked() & noexcept {
    XPP_DEBUG_ASSERT(m_has_value, "internal: Option must be Some");
    return *reinterpret_cast<T*>(&m_storage);
}

Implementation Notes

do_panic is defined in panic.cpp (not header-only) to avoid pulling in the libx logging dependency transitively. A type-safe printf-style __attribute__((format(printf, 1, 2))) on GCC/Clang lets the compiler validate format strings at every macro use site.

XPP_ASSERT uses XPP_UNLIKELY to hint the branch predictor that the assertion rarely fires, keeping the hot path in the instruction cache.

event.h — RAII Event Loop Wrapper

Introduction

event.h provides C++ RAII wrappers for the libx event loop. Two classes with distinct responsibilities:

• EventLoop — Owns the xEventLoop handle. Creates on construction, destroys when out of scope. Move-only.
• WaitScope — Binds the loop to the current thread (xEventLoopEnter/Leave). Non-copyable, non-movable — tied to its scope.

This separation mirrors the C API where xEventLoopCreate/Destroy and xEventLoopEnter/Leave are independent operations. EventLoop manages the resource; WaitScope manages the thread binding.

Design Philosophy

1. Handle ownership vs. thread binding are separate concerns. Creating a loop and binding it to a thread are two orthogonal operations. Collapsing them into a single RAII type would complicate sharing and lifetime management.

2. WaitScope is scope-tied, not a movable object. xEventLoopEnter/Leave form a stack-like pair. Moving the guard would leave the original scope without a corresponding Leave, violating the contract.

3. The handle itself is thread-safe. stop(), wake(), and xEventLoopPost can be called from any thread. run(), xTimerStart, and xEventAdd must be called from the entered thread.

4. EventLoop::current() panics outside WaitScope. This catches the common bug of calling Promise::await() without an active event loop binding.

5. Fiber integration. With XPP_FIBER, PromiseContext::park() can suspend a fiber via xFiberYield() instead of blocking the thread with X_RUN_ONCE. The same WaitScope and EventLoop drive all fibers — no separate scheduler needed. See .await() docs.

API Reference

EventLoop

RunMode

WaitScope

Usage Examples

Basic event loop

#include <xpp/event.h>
#include <xpp/timer.h>

int main() {
    xpp::EventLoop loop;

    {
        xpp::WaitScope scope(loop);

        // One-shot: fire once after 100ms, then stop the loop
        xpp::Timer(100, 0, [&]() { loop.stop(); });

        loop.run();  // Blocks ~100ms, then timer fires → stop
    }
    // WaitScope leaves the loop here
}

Interop with Promise<T>

#include <xpp/event.h>
#include <xpp/promise.h>
#include <xpp/timer.h>

xpp::EventLoop loop;
{
    xpp::WaitScope scope(loop);

    auto r = xpp::PromiseResolver<int>::create();

    xpp::Timer(50, 0, [&]() { r.resolve(42); });

    int result = r.promise().await();  // EventLoop::current() succeeds
}

Manual wake from another thread

#include <thread>

xpp::EventLoop loop;
{
    xpp::WaitScope scope(loop);

    std::thread worker([&]() {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
        loop.wake();   // Thread-safe: unblocks epoll_wait
        // or: loop.stop();
    });

    loop.run();
    worker.join();
}

Comparison

Implementation Notes

Storage

class EventLoop {
    OwnedOpaquePointer<Destroy> m_loop;
};

EventLoop stores an OwnedOpaquePointer<Destroy> — essentially Own<void, Destroy> — where Destroy is a stateless deleter that calls xEventLoopDestroy. The handle itself is opaque; operator bool() delegates to Own::operator bool().

EventLoop::current()

static xEventLoop current() {
    xEventLoop loop = xEventLoopCurrent();
    XPP_ASSERT(loop != nullptr, "EventLoop::current() called outside WaitScope");
    return loop;
}

On macOS/Linux, xEventLoopCurrent() reads a __thread / thread_local variable set by xEventLoopEnter. No global registry, no lookup — pure thread-local storage. The assert catches the case where no WaitScope is active on the calling thread.

Promise<T> — Composable Deferred Values

← libxpp

Introduction

Promise<T> provides a type-safe async programming system within the libx event loop. It combines the poll-based model from Rust's Future trait with the node-hierarchy and per-chain arena allocation from KJ (Cap'n Proto), plus stackful fiber support via xpp::fiber().

The core API (.then(), .await(), resolve(), all(), race()) is C++11. C++20 is required only for co_await / co_return.

Promise<T> supports three equivalent coding styles — pick whichever fits your compiler and preference:

C++11 + .await() (works everywhere):

xpp::Promise<int> compute() {
    return fetch_value()
        .then([](int x) { return x * 2; });
}
int result = compute().await();  // drives event loop if not in fiber

C++11 + fiber (non-blocking inside xpp::fiber()):

int result = xpp::fiber([]() {
    int x = fetch_value().await();     // fiber suspends, event loop continues
    return x * 2;
}).await();

C++20 co_await / co_return:

xpp::Promise<int> compute() {
    int x = co_await fetch_value();
    co_return x * 2;
}
int result = compute().await();

All three are backed by the same poll()-based state machine.

Design Philosophy

1. .await() First — .await() is the universal entry point. Outside a fiber it drives xEventLoopRun() directly. Inside a fiber (via xpp::fiber()) it suspends the fiber via xFiberYield() — non-blocking, stackful concurrency without co_await syntax.
2. One-Shot Polling — poll() returns Option<T>: Some(value) = ready, None = pending. No separate take().
3. Single-Threaded Executor — Like Tokio's current_thread runtime. The event loop is both reactor (I/O) and scheduler (timers/callbacks). No background thread pool needed.
4. Auto-Flatten — .then(fn) returning Promise<U> becomes Promise<U>, not Promise<Promise<U>>.
5. Lock-Free Cross-Thread Resolve — PromiseResolver holds ArcWeak; resolve() silently drops if Promise is destroyed.
6. Void-Aware Templates — Void + FixVoid<T> maps void → Void for uniform generic code.
7. Nested .await() Is Safe — WaitScope owns the loop binding; nested Run calls don't unbind it.
8. Per-Chain Arena — .then() chains bump-allocate nodes in a shared 256-byte arena, reducing malloc calls from O(N) to O(1) per chain. Overflow nodes fall back to heap transparently.
9. Coroutine-Native — Promise<T> is both a poll-based node container and a C++20 coroutine return type. co_await drives the same poll() mechanism as .then().
10. Adapter Pattern — External async operations (timers, thread pool, custom I/O) bridge into the poll world via AdapterPromiseNode + PromiseResolver.

Architecture

graph TD
    subgraph "User API"
        PR["resolve(v)"]
        CHAIN[".then(fn)"]
        AWAIT[".await()"]
        FIBER["xpp::fiber()"]
        ASYNC["async<T>()"]
        PRR["PromiseResolver<T>"]
        CORO["co_await / co_return"]
    end

    subgraph "PromiseNode Hierarchy"
        BASE["PromiseNode&lt;T&gt;<br/>poll(waker) → Option&lt;T&gt;"]
        IMM["ImmediatePromiseNode"]
        TRANS["TransformPromiseNode"]
        CHAINP["ChainPromiseNode"]
        ADAPT["AdapterPromiseNode&lt;T, Adapter&gt;"]
        MANUAL["ManualResolveNode&lt;T&gt;"]
        COROP["CoroutinePromiseNode&lt;T&gt;"]
    end

    subgraph "Shared State"
        RS["ResolveState&lt;T&gt;<br/>Arc / ArcWeak"]
        AW["AtomicPromiseWaker"]
        ARENA["PromiseArena (256B)<br/>per-chain bump allocator"]
        FIB["xFiber / xFiberYield<br/>stackful suspend"]
    end

    PR --> IMM
    CHAIN --> TRANS
    CHAIN --> CHAINP
    ASYNC --> MANUAL
    ASYNC --> PRR
    PRR --> RS
    ADAPT --> RS
    CORO --> COROP
    AWAIT --> BASE
    FIBER --> FIB
    FIB --> AWAIT
    BASE --> AW
    RS --> AW
    TRANS -.->|arena-allocated| ARENA
    CHAINP -.->|arena-allocated| ARENA

    style AWAIT fill:#4a90d9,color:#fff
    style FIBER fill:#50b86c,color:#fff
    style RS fill:#e91e63,color:#fff
    style ADAPT fill:#50b86c,color:#fff
    style ARENA fill:#f5a623,color:#fff
    style CORO fill:#9b59b6,color:#fff
    style FIB fill:#4a90d9,color:#fff

Topics

• .await() & Fiber — .await() semantics, fiber suspend, event loop integration
• then() — chaining, auto-flatten, type transformations
• Deferred Resolution — async(), PromiseResolver, cross-thread resolve
• Timers & Timeouts — after(ms), timeout pattern with race
• Combinators — all(), race(), concurrent composition
• Utilities — try_next(), sequential fall-through
• Custom Adapters — adapt, work, Adapter contract, TimerAdapter, WorkAdapter
• C++20 Coroutines — co_await / co_return with Promise<T> (no Task<T>)
• Internals — PromiseNode hierarchy, waker system, ResolveState

API Reference

Promise<T>

PromiseResolver<T>

Free Functions

.await() — Waiting for a Promise

← Promise<T>

.await() is the canonical way to extract a value from a Promise<T>. It's context-aware — the same call behaves differently depending on where you are.

Outside a fiber:          Inside xpp::fiber():
  park()                    park()
    X_RUN_ONCE               xFiberYield()
    (thread blocks)          (fiber suspends, event loop keeps running)

Two contexts, one API

1. Direct (non-fiber) — drives the event loop

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

int result = fetch_value()              // Promise<int>
    .then([](int x) { return x * 2; })
    .await();                           // runs X_RUN_ONCE until resolved

2. Inside a fiber — non-blocking suspend

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

xpp::fiber([]() {
    auto a = http_get("/a").await();    // fiber suspends
    auto b = http_get("/b").await();    // resumes when a is ready
    return a + b;
}).then([](int total) {
    printf("total = %d\n", total);
});

loop.run();  // one thread drives all fibers + I/O

This is the key insight: .await() means "wait for this Promise, letting the event loop continue in the meantime". Outside a fiber, you run the loop. Inside a fiber, you return control to the loop.

How it works

// Simplified — the real implementation is in PromiseContext::park()
T Promise<T>::await() {
    PromiseContext cx;         // auto-detects fiber context
    while (true) {
        Option<T> result = m_node->poll(cx);
        if (result.is_some()) return result.unwrap();
        cx.park();             // fiber: xFiberYield | non-fiber: X_RUN_ONCE
    }
}

1. Poll — ask the promise node if the value is ready.
2. Park — if not ready, let the event loop make progress:
   • Fiber: suspend via xFiberYield(), the event loop runs on the main stack, and the waker switches back when the promise resolves.
   • Non-fiber: call xEventLoopRun(X_RUN_ONCE) to process one batch of events (timers, I/O, done queue).
3. Repeat until poll() returns Some<T>.

Nested .await() is safe

A promise chain can call .await() on another promise — the WaitScope uses a thread-local pointer, so nested calls don't unbind the outer scope.

Promise<User> fetch_user() {
    return fetch_id().then([](int id) {
        return fetch_from_db(id).await(); // nested await — safe
    });
}

User u = fetch_user().await();

.await() in tests

Almost every test follows this pattern:

TEST(MyTest, Example) {
    xpp::EventLoop loop;
    xpp::WaitScope scope(loop);
    my_test_coroutine().await();  // drive to completion
}

await() vs co_await

They're the same mechanism at different levels. .await() is the universal entry point — it works everywhere. co_await is a C++20 sugar inside coroutine functions.

then() — Chaining & Auto-Flatten

← Promise<T>

then() is the primary chaining mechanism for Promise<T>. It transforms a resolved value into a new Promise, with automatic flattening.

Basic chaining — .await()

xpp::resolve(10)
    .then([](int x) { return x * 2; })   // Promise<int>
    .then([](int x) { return x + 1; })   // Promise<int>
    .then([](int x) {                     // Promise<void>
        printf("result: %d\n", x);
    });
// final chain: Promise<void>

Each .then() adds one link to the chain. The chain only starts running when the root promise (here resolve(10)) is polled by the event loop.

Auto-Flatten

If a .then() callback returns a Promise<U>, the result is flattened to Promise<U> — not Promise<Promise<U>>. This is the same behavior as Rust's Future::and_then and JavaScript's Promise.then.

Promise<User> fetch_user(int id) { /* ... */ }
Promise<Order> fetch_order(User &u) { /* ... */ }

Promise<Order> order = resolve(42)
    .then([](int id) { return fetch_user(id); })   // → Promise<User> (flattened)
    .then([](User u) { return fetch_order(u); });   // → Promise<Order> (flattened)

Without auto-flatten, the result would be Promise<Promise<User>> — requiring .then().then() to unwrap. With it, you write a flat chain.

Type transformations

Promise<std::string> msg = resolve(10)
    .then([](int x)  { return x * 2; })            // Promise<int>
    .then([](int x)  { return std::to_string(x); }); // Promise<std::string>

Each .then(fn) turns Promise<T> into Promise<decltype(fn(T))>. The compiler tracks types through the entire chain.

Void handling

Promise<> p = resolve(10)
    .then([](int x) { printf("%d\n", x); });
// p is Promise<void>

then() is non-mutating

Each .then() call returns a new Promise — the original is untouched. This means you can fork a chain into multiple consumers:

auto root     = fetch_value();
auto doubled  = root.then([](int x) { return x * 2; });
auto tripled  = root.then([](int x) { return x * 3; });

Error handling

There's no built-in catch method. Errors are propagated through the chain as regular values using Result<T, E>:

Promise<Result<int, MyError>> compute = resolve(42)
    .then([](int x) -> Result<int, MyError> {
        if (x == 0) return err(MyError::DivideByZero);
        return ok(100 / x);
    })
    .then([](Result<int, MyError> r) {
        return r.is_ok() ? r.unwrap() * 2 : 0;
    });

Arenas: allocation model

Each .then() chain shares a 256-byte bump allocator (arena). Promise nodes are allocated from this arena, not individually heap-allocated. This means a 10-link chain is a single malloc (the arena) rather than 10 separate allocations. Nodes that overflow the arena fall back to heap transparently.

Driving the chain

Chains are lazy — nothing runs until polled. Use .await() to drive the chain to completion on the current thread:

int result = resolve(10)
    .then([](int x) { return x * 2; })
    .await();
// result == 20

then() vs .await() vs co_await

These three are equivalent:

// C++11: then() + .await()
Promise<int> p = fetch_value()
    .then([](int x) { return x * 2; });

// C++11 + fiber: .await()
int val = xpp::fiber([]() {
    int x = fetch_value().await();
    return x * 2;
}).await();

// C++20: co_await
Promise<int> p = async_compute();  // inside: int x = co_await fetch_value(); co_return x * 2;

All produce the same Promise<int> backed by the same poll() mechanism.

Deferred Resolution

← Promise

When to Use

You have an async operation that completes later (timer, network, thread pool) and want to create a Promise that resolves when it finishes.

xpp::async<T>()

Returns std::pair<Promise<T>, PromiseResolver<T>>. The resolver is safe to call after the Promise is destroyed — it holds ArcWeak, so resolve() silently drops if the Promise is gone.

#include <xpp/promise.h>
#include <xpp/promise_adapter.h>

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

auto [p, r] = xpp::async<int>();

// Resolve from a timer callback
xpp::Timer t(100, 0, [&]() { r.resolve(42); });

int result = p.await();  // blocks ~100ms
// result == 42

Cross-Thread Resolve

resolve() is thread-safe — ArcWeak::upgrade() is a CAS loop. Safe to call from any thread.

#include <thread>

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

auto [p, r] = xpp::async<std::string>();

std::thread worker([&]() {
    std::this_thread::sleep_for(std::chrono::milliseconds(50));
    r.resolve(std::string("from another thread"));
});

std::string result = p.await();
// result == "from another thread"
worker.join();

Safe After Promise Destruction

If the Promise is destroyed before resolve() is called (e.g., a losing branch in race()), resolve() silently drops — no UAF.

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

xpp::PromiseResolver<int> r;
{
    auto [p, r2] = xpp::async<int>();
    r = std::move(r2);
    // p is destroyed when the scope ends
}
// Promise is gone. resolve() safely drops.
r.resolve(42);
// No crash.

Double Resolve

Only the first resolve() takes effect. Subsequent calls are silently dropped via compare_exchange_strong on the resolved flag.

auto [p, r] = xpp::async<int>();
r.resolve(42);
r.resolve(99);  // silently dropped
EXPECT_EQ(p.await(), 42);

Nested wait()

wait() inside a .then() callback is safe — WaitScope owns the loop binding, nested xEventLoopRun doesn't unbind it.

auto [outer_p, outer_r] = xpp::async<int>();
auto [inner_p, inner_r] = xpp::async<int>();

// Schedule: outer at 60ms, inner at 30ms
// ...

int result = outer_p
    .then([&](int outer_val) {
        int inner_val = inner_p.await();  // nested Run
        return outer_val + inner_val;
    })
    .await();

Best Practices

• PromiseResolver can safely outlive the Promise. ArcWeak — resolve() silently drops. No UAF.
• is_pending() is not atomic. Check only from the owner thread.
• Don't wait() on an empty promise. Check operator bool() first.
• Nested wait() is safe but beware deadlocks. If the inner promise is never resolved, wait() spins indefinitely.

Timers & Timeouts

← Promise

When to Use

You need a delay, a timeout, or want to race a Promise against a timer.

after(ms)

Resolves after ms milliseconds. Available only on Promise<void>. Chain with .then() to run code after the delay.

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

xpp::after(100)
    .then([]() { printf("100ms elapsed\n"); })
    .await();

Internally uses AdapterPromiseNode<void, TimerAdapter>. The TimerAdapter owns an xTimer handle:

• Timer fires → callback calls m_resolver.resolve() → sets resolved=true, wakes poller
• Promise destroyed early → ~TimerAdapter() calls xTimerStop (if not yet fired, checked via m_fired atomic flag)
• Loop destroyed → on_cancel callback nulls m_handle, sets m_fired=true

The promise must be destroyed on the same WaitScope thread.

Timeout Pattern with race

Combine after() with race() to implement timeouts:

#include <xpp/promise_combinators.h>

xpp::EventLoop loop;
xpp::WaitScope scope(loop);

// Fetch takes 100ms, timeout is 10ms → timeout wins
int result = xpp::race(
    xpp::after(100).then([] { return 200; }),  // "fetch"
    xpp::after(10).then([] { return -1; })     // timeout
).await();
// result == -1 (timeout)

When race resolves, the losing branch is destroyed. TimerAdapter's destructor calls xTimerStop — the 100ms timer is cancelled, no callback fires after destruction.

Sequential Delays

xpp::after(10)
    .then([]() { return xpp::after(20); })  // auto-flattened
    .then([]() { printf("30ms total\n"); })
    .await();

Void Promise Chains

int counter = 0;
xpp::yield()
    .then([&]() { counter++; })
    .then([&]() { counter++; })
    .await();
// counter == 2

lazy() and yield()

// defer: wrap a sync function as a promise
int result = xpp::lazy([] { return 42; }).await();
// result == 42

// yield: immediately-resolved Promise<void>, chain entry point
int val = xpp::yield().then([] { return 1; }).await();
// val == 1

Combinators: all and race

← Promise

When to Use

You need to wait for multiple Promises concurrently (all) or take the first result (race).

xpp::all(Promise<Ts>...)

Waits for all input promises, collecting results into a std::tuple.

• Heterogeneous: each promise may have a different type
• All-void: returns Promise<void> (not Promise<tuple<Void, Void, ...>>)
• Zero arguments: rejected by static_assert

#include <xpp/promise_combinators.h>

// Heterogeneous — returns tuple
auto [status, body] = xpp::all(
    fetch_status(url),   // Promise<int>
    fetch_body(url)      // Promise<std::string>
).await();

// All-void — returns void
xpp::all(
    prefetch(0),
    prefetch(1),
    prefetch(2)
).then([] { start_playback(); }).await();

// With void + value — Void in tuple, ignored
auto [_, val] = xpp::all(
    yield(),
    resolve(42)
).await();
// val == 42

xpp::race(Promise<T> first, Promise<Rest>...)

Resolves with the first ready promise. All losing branches are destroyed.

• Homogeneous: all promises must have the same type T
• Void support: race(Promise<void>...) returns Promise<void>

// Timeout pattern
auto result = xpp::race(
    fetch_async(url),                                        // Promise<int>
    xpp::after(5000).then([] { return -1; })  // timeout
).await();

// N CDNs, take fastest
auto fastest = xpp::race(fetch(cdn1), fetch(cdn2), fetch(cdn3)).await();

// Void race
xpp::race(after(10), after(50)).await();
// resolves at ~10ms

How Waker Sharing Works

Both all and race pass the same PromiseContext to all children. When any child fires the waker (via cx.waker().wake()), await() re-polls the parent node.

Re-polling is safe because the parent tracks which children are done:

• AllTuplePromiseNode: checks Option::is_some() per child
• RacePromiseNode: returns on first Some, remaining children destroyed

wait() uses X_RUN_ONCE

Promise::wait() runs the event loop with X_RUN_ONCE (one iteration per call) rather than X_RUN_DEFAULT. This is critical for race: with two timers, the faster timer sets woken = true, but the slower timer keeps the loop alive. X_RUN_ONCE returns after each event, letting wait() re-check woken immediately.

Destruction Safety for race

When race resolves, N-1 losing children are destroyed:

With ArcWeak-based PromiseResolver, destroying an AdapterPromiseNode is safe — resolve() finds upgrade() == None and silently drops. No UAF.

Comparison with Other Languages

Utilities: try_next

← Promise

When to Use

You need to try multiple items with an async function, returning the first success — like falling through a list of DNS addresses until one connects.

xpp::try_next(items, fn)

Calls fn(item) on each item in items sequentially. Returns the first ok result, or the last err if all fail.

• C++11-compatible: uses struct + std::move(*this) chaining, no coroutines or concepts
• Zero heap allocation in the combinator itself (items and fn stored by value)
• Duck-typed: fn(item) must return Promise<Result<T, E>> where Result has .is_ok()
• Factory function: try_next(items, fn) returns a callable; invoke with () to start

#include <xpp/promise_utils.h>

// Try each resolved DNS address until one connects
std::vector<SocketAddr> addrs = co_await resolve_host("example.com");
auto stream = xpp::try_next(std::move(addrs), [&](const SocketAddr &a) {
    return TcpStream::connect_with_conf(a.ip().c_str(), a.port(), conf.get());
})().await();

// Returns first ok, or last error (ConnectionRefused from final address)

Immediate results

When fn returns immediately-resolved promises, try_next evaluates without touching the event loop:

std::vector<int> items = {10, 20, 30};

auto result = xpp::try_next(std::move(items), [](int x) -> Promise<Result<int, int>> {
    if (x == 20) return xpp::resolve(Result<int, int>(ok, x * 10));
    return xpp::resolve(Result<int, int>(err, -x));
})().await();
// result == 200 (20 × 10), only tried 10 (failed) and 20 (ok)

Fall-through chain

When all items fail, returns the last error:

std::vector<int> items = {1, 2, 3};

auto err = xpp::try_next(std::move(items), [](int x) -> Promise<Result<int, int>> {
    return xpp::resolve(Result<int, int>(err, x));
})().await();
// err == 3, all three were tried

Deferred (async) results

Works with async operations scheduled on the event loop:

std::vector<int> items = {10, 20, 30};

auto ar1 = xpp::async<Result<int, int>>();
auto ar2 = xpp::async<Result<int, int>>();

// r1 resolves with error at 10ms, r2 resolves with success at 20ms
schedule_resolve(ar1.second, Result<int, int>(err, -1), 10);
schedule_resolve(ar2.second, Result<int, int>(ok, 99), 20);

auto result = xpp::try_next(std::move(items), [&, p1 = std::move(ar1.first),
                                                  p2 = std::move(ar2.first)]
                            (int) mutable -> Promise<Result<int, int>> {
    static int call_count = 0;
    call_count++;
    if (call_count == 1) return std::move(p1);
    return std::move(p2);
})().await();
// result == 99 (second item succeeded after the first failed)

How It Works

TryNext<Items, Func> is a callable struct. Calling operator() pushes the first item through fn(), then chains a .then() callback:

// Simplified:
struct TryNext {
    Items items;
    size_t idx;
    Func fn;

    P operator()() {
        return fn(items[idx++]).then(Then{std::move(*this)});
    }

    struct Then {
        TryNext next;  // ownership transferred via move
        template <class R>
        P operator()(R &&r) {
            if (r.is_ok()) return xpp::resolve(std::forward<R>(r));
            if (next.idx >= next.items.size())
                return xpp::resolve(std::forward<R>(r));  // last error
            return next();  // try next item
        }
    };
};

Key design points:

• std::move(*this) ownership transfer: the TryNext struct (with items and fn by value) moves through each .then() node in the Promise chain — no shared_ptr refcount overhead
• Template operator() in Then: accepts Result<T, E> without spelling out the types, enabling duck-typing of any Result type with .is_ok()
• Tail-recursive via Promise chain: return next() creates a new .then() link, rather than growing the call stack

Performance

The combinator itself is zero-allocation. The Promise chain uses xpp's per-chain arena allocator, so only the head node hits the heap — subsequent .then() nodes are bump-allocated in the arena.

Why Not try_each?

The original name was try_each, but that misleadingly implies all items are always tried. The actual semantics are "try one, fail → try the next, succeed → stop". try_next captures this accurately: it parallels try_next() / next() iteration patterns in Rust's Iterator trait.

Custom Adapters

← Promise

When to Use

You have an async operation (HTTP fetch, DNS lookup, thread pool work) and want to bridge it into the Promise system with automatic cancellation when the Promise is destroyed.

Adapter Contract

An Adapter is a class with:

• Constructor: receives PromiseResolver<T>&& + user args. Starts the async operation.
• Destructor: cancels the async operation (if still in-flight).
• Async callback: calls resolver.resolve(value) when done. Safe to call from any thread.

class MyAdapter {
  PromiseResolver<int> m_resolver;
public:
  MyAdapter(PromiseResolver<int>&& r, const char* url)
    : m_resolver(std::move(r)) {
    // Start async fetch...
    // When done: m_resolver.resolve(response_code);
  }
  ~MyAdapter() {
    // Cancel the fetch if still in-flight
  }
};

adapt<T, Adapter>(args...)

#include <xpp/promise_adapter.h>

auto p = xpp::adapt<int, MyAdapter>(url);
// MyAdapter is constructed with (PromiseResolver<int>&&, url)
// When the fetch completes, MyAdapter calls resolver.resolve(code)
int code = p.await();

How It Works

AdapterPromiseNode<T, Adapter>
  ├─ Arc<ResolveState<T>> m_state    ← strong ref (keeps state alive)
  ├─ Adapter m_adapter               ← owns the async operation
  │    └─ PromiseResolver<T>         ← weak ref (ArcWeak to state)
  │
  ├─ poll(waker):                    ← generic, same for all adapters
  │    if resolved → return value
  │    else register waker → re-check → return None
  │
  └─ ~dtor: ~Adapter() → ~Arc()     ← cancel op, then drop strong ref

ResolveState — Shared via Arc/ArcWeak

struct ResolveState<T> {
  Option<T>          value;
  AtomicPromiseWaker waker;
  std::atomic<bool>  resolved{false};
};

• AdapterPromiseNode holds Arc<ResolveState<T>> (strong) — keeps state alive.
• PromiseResolver holds ArcWeak<ResolveState<T>> (weak) — resolve() calls upgrade().
• When node is destroyed → strong count → 0 → upgrade() returns None → resolve() silently drops.