Sane C++ Libraries
Cross-platform APIs and agent-assisted development.
Sane C++ Libraries is my
personal project.
It is not an NVIDIA product.
A cross-platform
systems-programming base layer.
Independent libraries for common runtime facilities.
Designed to compose, from one library to a whole application.
Repository begins.
Fast builds, readable code,
easy integration.
Increasing delegation
of implementation.
“I no longer manually
write the code.”
Common runtime facilities with explicit dependencies.
The same Process API with three integration choices.
#define SANE_CPP_IMPLEMENTATION
#include "SaneCppProcess.h"
int main()
{
SC::Process git;
if (!git.exec({"git", "--version"})) return 1;
return git.getExitStatus();
}clang++ main.cpp -o demoSelf-contained Process header beside main.cpp. Tested with this compiler’s default and with C++14.
#include "SaneCppProcess.h"
int main()
{
SC::Process git;
if (!git.exec({"git", "--version"})) return 1;
return git.getExitStatus();
}cl /permissive- /I SC\Includes main.cpp SC\SC.cpp /Fe:demo.exeSC is the repository checkout. MSVC links the system libraries through the source’s pragma directives.
// sc-build-version: main
#include "SaneCppBuild.h"
SC::Result SC::Build::configure(
Definition& d, const Parameters& p)
{
Project project = {"Demo"};
SC_TRY(project.addFiles(".", "main.cpp"));
SC_TRY(addSaneCppLibraries(project, p));
return d.addProject(move(project));
}#include "SaneCppProcess.h"
int main()
{
SC::Process git;
if (!git.exec({"git", "--version"}))
return 1;
return git.getExitStatus();
}./SC-build.sh compile Demo DebugCopy SC-build.sh into the project. The version marker selects Sane; first run downloads/caches it.
Result readConfig(FileDescriptor& file) {
char storage[4096];
Span<char> bytes;
SC_TRY(file.read(storage, bytes));
// Use bytes only after success.
return Result(true);
}#define SC_TRY(expression) \
do { \
auto _exprResConv = \
SC::Result::Explicit(expression); \
if (!_exprResConv) \
return _exprResConv; \
} while (false)Evaluate once. On failure, return immediately. On success, continue.
enum class FileError : uint32_t {
InvalidHandle = 1,
UnsupportedPathEncoding,
InvalidPath,
// More errors omitted.
};
constexpr ResultCategory
FileResultCategory{10};Result lowerLevel() {
return Result::Error(
FileResultCategory,
FileError::InvalidPath);
}
Result higherLevel() {
SC_TRY(lowerLevel());
return Result(true);
}const Result result = higherLevel();
if (result.isError(FileResultCategory, FileError::InvalidPath)) {
// Ask for a different path, or report this specific failure.
}EADDRINUSEWSAEADDRINUSEResultSocket result = server.bind(address);
if (result.contextKind == SocketErrorContextKind::NativeError) {
console.print("OS error: {}\n", result.context.nativeError);
}
if (result.isError(SocketError::AddressInUse)) {
// Offer a different port, independent of the operating system.
}
Result portable = result; // Category + error code only.Keep ResultSocket when you need the native code and operation detail.
Process first, second;
ProcessChain chain;
SmallString<128> captured;
SC_TRY(chain.pipe(first, {"cat"}));
SC_TRY(chain.pipe(second, {"grep", "Sane"}));
SC_TRY(chain.exec(captured, "Hello\nSane C++\n"));
// stdout, stdinprintf 'Hello\nSane C++\n' | cat | grep SaneSocketDescriptor listener, client;
SocketIPAddress address;
SC_TRY(address.fromAddressPort("127.0.0.1", port));
SC_TRY(listener.create(address.getAddressFamily()));
SocketServer server(listener);
SC_TRY(server.bind(address));
SC_TRY(server.listen(8));
SC_TRY(server.accept(address.getAddressFamily(), client));FileDescriptor file;
SC_TRY(file.open(absolutePath, FileOpen::Read));
char storage[4096];
Span<char> bytes;
SC_TRY(file.read(storage, bytes));A C array converts to a typed Span. For a vector: {storage.data(), storage.size()}.
FileSystemIterator::FolderState levels[16];
FileSystemIterator walk;
walk.options.recursive = true;
SC_TRY(walk.init(rootPath, levels));
while (walk.enumerateNext())
{
inspect(walk.get().path);
}
SC_TRY(walk.checkErrors());FileSystemWatcher::ThreadRunner runner;
FileSystemWatcher watcher;
FileSystemWatcher::FolderWatcher folder;
SC_TRY(watcher.init(runner));
folder.notifyCallback = [&](const auto& notification) {
StringPath path;
if (notification.getFullPath(path))
console.print("Changed: {}\n", path.view());
};
SC_TRY(watcher.watch(folder, directoryPath));Print the affected path. ThreadRunner here; event-loop delivery is also available.
Requests, buffers and callback state must remain stable until completion.
AsyncFileRead read;
char buffer[4096];
read.buffer = buffer; // Span<char>: address + extent
read.callback = [&](auto& result) // AsyncFileRead::Result
{
Span<char> bytes;
if (result.get(bytes))
received = bytes.sizeInBytes() == 4;
};
SC_TRY(read.start(loop));
SC_TRY(loop.run());read is a caller-owned request.
buffer converts to Span<char>. Its size stays part of the contract.
bytes views the completed portion.
loop.run() dispatches the callback while this scope stays alive.
Sane C++ supports the major async paradigms: callbacks, fibers and coroutines.
AwaitSocketReceiveResult received;
SC_CO_TRY(co_await await.receive(socket, buffer, received));
SC_CO_TRY(co_await await.sendAll(socket, received.data));
co_return Result(true);Receive one chunk, then echo it. received.data is a Span over the supplied buffer.
AsyncFiberSocketReceiveResult received;
SC_TRY(io.receive(socket, buffer, received));
SC_TRY(io.sendAll(socket, received.data));
return Result(true);The same I/O, expressed as sequential code on a caller-supplied fiber stack.
Built with Codex during this conference, inspired by Alberto Barbati’s earlier talk.
AsyncReadableFileStream<AsyncEventLoop> source;
AsyncZLibTransformStreamT<AsyncEventLoop> compressor;
AsyncWritableSocketStream<AsyncEventLoop> destination;
// File, socket, compression and queue setup omitted.
AsyncPipeline pipeline;
pipeline.source = &source;
pipeline.transforms[0] = &compressor;
pipeline.sinks[0] = &destination;
SC_TRY(pipeline.pipe());
SC_TRY(pipeline.start());SC_TRY(registry.loadPlugin(id, compiler, sysroot, hostPath));
PluginDynamicLibrary* module = registry.findPlugin(id);
ITransform* api = nullptr;
SC_TRY_MSG(module && module->queryInterface(api), "interface");
const int value = api->transform(2);
SC_TRY(registry.unloadPlugin(id));struct ITransform {
static constexpr auto InterfaceHash =
PluginHash("ITransform");
Function<int(int)> transform;
};A typed interface across a dynamically loaded module boundary.
Personal experience and expectations · reevaluate as models change.
The entire library set is structured around caller-provided storage.
char storage[4096];
Span<char> bytes;
SC_TRY(file.read(storage, bytes));FileSystemIterator::FolderState levels[16];
FileSystemIterator walk;
SC_TRY(walk.init(rootPath, levels));char storage[4096];
AsyncFileRead read;
read.buffer = storage; // Span<char>struct Slot
{
// One compile job owns this whole group.
AsyncProcessExit exited;
AsyncFileRead stdoutRead, stderrRead;
PipeDescriptor stdoutPipe, stderrPipe;
SmallVector<char, 4096> stdoutBuffer, stderrBuffer;
bool processFinished = false;
bool stdoutFinished = false, stderrFinished = false;
// Reuse the group only after its LAST completion.
bool reusable() const
{ return processFinished
&& stdoutFinished && stderrFinished; }
};FIRST: start monitoring a compile job.
Keep its monitor, reads, pipes and buffers together.
LAST: process exit + both streams finished.
Only then can the whole slot serve another job.
Completion of one request does not end the group’s lifetime.
A finished process can still have unread output. Keep the whole slot alive until all three completions.
Compiler launched. The slot owns the process and both read requests.
#include <Windows.h>#include <sys/socket.h>#include <CoreServices/CoreServices.h>
#pragma once
// Sane types and declarations only.
namespace SC {
struct AsyncEventLoop;
struct AsyncFileRead;
// Public API declarations...
}Less parsing.
Fewer leaked symbols.
No imported OS macros.
template <typename CharIterator>
struct StringIterator {
bool reverseAdvanceUntilMatches(CodePoint c);
// ...
};template <typename CharIterator>
bool StringIterator<CharIterator>::
reverseAdvanceUntilMatches(CodePoint c)
{
// Implementation lives here.
}
template bool StringIterator<StringIteratorUTF8>::
reverseAdvanceUntilMatches(CodePoint);
// Also explicitly instantiated: ASCII, UTF16.A public header is part of every consumer’s compilation environment.
OS headers stay behind the implementation boundary—including their macros.
Known template instantiations can be compiled once, with the body outside the public header.
// Private descriptor-flag helper (excerpt).
int oldFlags = ::fcntl(fd, F_GETFL);
// Check errors; retry EINTR (omitted).
const int newFlags = enabled
? oldFlags | O_NONBLOCK
: oldFlags & ~O_NONBLOCK;
// If changed: fcntl(fd, F_SETFL, newFlags).
// Check errors; retry EINTR (omitted).// Private descriptor-flag helper (excerpt).
int oldFlags = ::fcntl(fd, F_GETFL);
// Check errors; retry EINTR (omitted).
const int newFlags = enabled
? oldFlags | O_NONBLOCK
: oldFlags & ~O_NONBLOCK;
// If changed: fcntl(fd, F_SETFL, newFlags).
// Check errors; retry EINTR (omitted).Both own their descriptor policy. Socket need not depend on File for a few flag operations.
#include "SaneCppAsyncStandalone.h"
// Loop and pipe setup omitted.
read.buffer = buffer;
read.callback = onRead;
if (not read.start(loop)) return 5;
if (not loop.run()) return 8;#include <asio/io_context.hpp>
#include <asio/readable_pipe.hpp>
#include <asio/writable_pipe.hpp>
#include <asio/connect_pipe.hpp>
#include <asio/buffer.hpp>
// async_read_some(...); loop.run();#include <uv.h>
// Loop, pipe and callbacks omitted.
uv_read_start(
reinterpret_cast<uv_stream_t*>(
&readPipe), allocate, onRead);
uv_run(&loop, UV_RUN_DEFAULT);One async pipe example, one changed translation unit. All three read four bytes.
One consumer · compile + link after an edit
| Library | First build from source | One consumer edit + link |
|---|
M1 Pro · median of 5 fresh builds / 12 edits · earlier baseline
First build scope differs: libuv includes CMake + its full 37-file C library.
Shared-header edit · 100 consumers + link · four compiler jobs
| Library | Fresh build · 4 jobs | Edit one .cpp | Edit header · 4 jobs | Edit header · serial |
|---|
M1 Pro · three rounds · measured compile + link wall time · implementation reused on edits
Controlled example: the same working pipe program repeated in 100 files. Raw reports include ranges.
One source tree on the host, mounted into both guests. Each OS builds its own configuration.
A real development thread: a fixture correction, followed by checks on all three hosts.
Linux via SSH · macOS locally · Windows Bash via SSH — against the same working folder.
The agent can propose a change. Repeatable checks test whether it fits the project.
GUI and frame loops need control over when callbacks run.
Expose submitRequests, blockingPoll and dispatchCompletions alongside run().
Collapsing the phases into run() and breaking GUI integration.
An ADR records a decision, its constraints, rationale and consequences.
Find it in Architecture/<library>/. It is persistent context for a new agent.
The API shows three phases. The ADR explains why all three must remain.
Types, contracts, setup and examples.
Caller-owned storage, grouped lifetimes and independent APIs.
Propose substantial changes. Preserve contracts.
Implement selected proposals and verify the result.
Three repository skills: use the APIs, carry the design, simplify the implementation.
The API skill helps an agent use the actual library contracts.
The style skill carries the architectural approach into your own libraries.
The simplification skill maintains a proposal board, decisions, evidence and validation.
Evaluate your skills on real tasks.
Revise the guidance when they fail.
For casual contributions, I value a precise problem description
more than a proposed code patch.
Reproduction steps, environment,
expected and actual behavior.
The use case, why it matters,
and how it fits the project.
An issue or PR can provide that input. Code is one possible solution;
I decide the implementation and whether the change belongs.
Core contributors already share the project context.
“the server should keep running and keep serving every other connection.”
Expected behavior · original issue excerpt
Reproducer disables AF_ALG on Linux.
My agent wrote the fix from the report.
Failed upgrades return an error;
the server keeps running.
Fixes #31
Co-authored-by: Francesco CozzutoCross-platform C++ libraries for coding agents.
github.com/Pagghiu/SaneCppLibrariesX / Twitter · @pagghiu_
A prototype built with Codex at C++ Day 2026 · 17 October.
AsyncExecution app;
SC_TRY(app.create(2));
auto sendEncoded = [&](StringSpan file, uint16_t port)
{
return app.readFile(file)
| ex::continues_on(app.getPoolScheduler())
| ex::then(base64Encode)
| ex::let_value([&, port](auto& message) noexcept {
return app.sendTCP("127.0.0.1", port, move(message));
});
};
SC_TRY(app.run(ex::when_all(
sendEncoded("first.txt", 19092),
sendEncoded("second.txt", 19093))));File I/O on the pool · Base64 on a worker · TCP through Async
readFilePool file I/Ocontinues_on → thenPool workerlet_value → sendTCPNative Async requestsreadFilePool file I/Ocontinues_on → thenPool workerlet_value → sendTCPNative Async requestswhen_allJoin both transfersDebug + Release: 319 assertions each.
Both payloads independently decoded and checked.
Missing-file error and sibling cancellation checked.
Possible next step: a proper specification.
Evaluate support alongside fibers and coroutines.
C++26 draft N5046 protocols · stdexec reference provider · native standard-library senders unavailable locally