pagghiu/sanecpplibraries/sane-cpp-libraries

Sane C++ Libraries

Help users compose the APIs that exist in this checkout, rather than translating them into STL-shaped abstractions or guessing overloads. This is an adoption skill, not a requirement to adopt all Sane libraries.

Start Here

• For integration or library selection, read getting started, then adoption if needed.
• For one library, read only its matching references/<topic>/guide.md; use the topic map for ambiguous requests.
• For an async process with pipe capture, read the composition recipe as well as async, file, and process.
• Before emitting code, verify the selected public header and the cited test or example in the local checkout. The source locations behind the composition guidance are in source anchors.

Composition rules that prevent real mistakes

• Treat a Result as an obligation: check it and propagate or classify it at the boundary. Do not infer successful I/O from EOF or ignore setup failures.
• Storage, descriptors, request objects, callback captures, and input views must outlive each active operation. The event loop does not own or move AsyncRequest objects.
• Define the completion predicate before writing callbacks. For a process with stdout and stderr capture, process exit alone is insufficient: wait for process completion and EOF/error handling on each stream before reuse or destruction.
• A recurring AsyncFileRead is reactivated only after its result is handled. Continue reading after a bounded capture buffer fills when draining is required; retain a prefix separately from the byte total.
• PipeOptions::blocking applies to pipe creation, not just the parent read end. Check the platform behavior and child contract before using a pipe as child stdout/stderr. Make inheritance deliberate: an extra inherited writer can suppress EOF.
• A deadline must participate in the event loop's blocking wait. Checking a clock before or after runOnce() does not bound a quiet wait; start an AsyncLoopTimeout or arrange an explicit wake-up before blocking.
• Moving a blocking descriptor operation to AsyncTaskSequence or a shared ThreadPool keeps the loop responsive, but the OS read remains blocking. Do not use that route when the task forbids blocking reads.
• Pass the descriptors expected by Process::launch; inspect the overload and the process tests rather than constructing its nested redirection types from guessed handles.
• For a capacity-bounded scheduler, make slots—not merely counters—reusable. Reset a slot only after its request/descriptors and completion predicate make reuse safe; separately reset or reconstruct stateful resources such as Process before the next logical operation.
• In a queued async workflow, a launch or setup failure may complete synchronously without a callback. If it frees capacity, schedule the next queued item before entering a blocking loop wait; a deadline wake-up is not a substitute for queue progress.
• Treat exit notification and OS resource reclamation as separate obligations until the selected backend/API proves otherwise. If the contract requires reaping, verify the normal completion path actually performs it.

Integration and verification

Use the smallest distribution route that meets the request: a single-file library for a narrow dependency footprint, or SC.cpp plus public library headers for multi-library work. Follow the selected guide for platform link requirements; do not include Internal or test headers in an application.

When changing Sane code, follow the repository's AGENTS.md, build the affected target before running it, run focused tests, and preserve independence checks where a new dependency could be introduced. When answering without changing code, say which header/test establishes any non-obvious claim.

Topic Guides

Onboarding And Navigation

• Adoption and integration: references/adoption/guide.md
• Best examples, tests, docs, and source entry points: references/examples/guide.md
• SC.sh, SC.bat, and custom tool invocation: references/tools/guide.md
• SC::Build project setup: references/build/guide.md
• Test layout and SCTest usage: references/testing/guide.md

Core Types And Data Structures

• Global rules and adaptation patterns: references/core-patterns/guide.md
• Foundation primitives such as Result, Span, and Function: references/foundation/guide.md
• Buffers, allocators, and owned storage: references/memory/guide.md
• Container choice and capacity behavior: references/containers/guide.md
• String formatting, conversion, and path helpers: references/strings/guide.md
• Time types and clock selection: references/time/guide.md
• Threads and synchronization primitives: references/threading/guide.md

I/O, Async, And Platforms

• Event loop, requests, and wake-up integration: references/async/guide.md
• Experimental coroutine wrapper over Async: references/await/guide.md
• Backpressure-aware stream pipelines: references/async-streams/guide.md
• Cross-library async composition recipes: references/async-networking/guide.md
• Raw synchronous sockets and DNS: references/socket/guide.md
• HTTP server, parser, and file server flows: references/http/guide.md
• Native-backend streaming HTTP client flows: references/http-client/guide.md
• Descriptor-based file and pipe I/O: references/file/guide.md
• Path-level filesystem operations: references/filesystem/guide.md
• Directory traversal: references/filesystem-iterator/guide.md
• File and folder change watching: references/filesystem-watcher/guide.md
• Child process launch and redirection: references/process/guide.md
• Serial port configuration and opening: references/serial-port/guide.md

Reflection, Serialization, And Plugins

• Reflection metadata and shape design: references/reflection/guide.md
• Reflection adapters for Sane containers: references/containers-reflection/guide.md
• End-to-end serialization choice and composition: references/serialization/guide.md
• Binary serialization flows: references/serialization-binary/guide.md
• Text and JSON serialization flows: references/serialization-text/guide.md
• Hashing algorithms and workflows: references/hashing/guide.md
• Runtime-loaded plugins and host exports: references/plugin/guide.md
• Plugin plus build-system integration recipes: references/plugin-build/guide.md