Repo refresh: user-facing docs, dev-artifact cleanup, opt-in huge pages - #1
Merged
Conversation
…d roadmap Delete the build-process ledger and internal planning docs (PROGRESS.md, SRS, implementation plan, agent prompt) — development history, not useful to library users. In their place: - docs/API.md: consolidated C ABI reference (all functions, error codes, lifecycle/sizing rules, zero-copy borrow rules, segment layout and flags contract, liveness caveat, Python/Rust binding patterns) — closes the long-standing NFR-M2 documentation gap. - docs/ROADMAP.md: triaged upgrade directions (already-shipped vs v1.x candidates vs exploratory). Makefile/ci.yml comments that pointed at PROGRESS.md now carry the explanation inline. .gitignore gains defensive entries for common editor/toolchain droppings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JykzcEronyifSN4RnTgjTk
… ABI v1.1) New create-time flag SHUTTLE_CREATE_HUGEPAGES advises the segment mapping with madvise(MADV_HUGEPAGE) on Linux — purely advisory (effective only where the kernel THP shmem policy permits), a no-op on macOS, never a correctness dependency. The flag is persisted in the header's cold identity block before the init_state release-store, so openers advise their own independent mapping too; unknown create-flag bits are masked and never persisted. The frozen v1 surface is untouched: shuttle_create keeps its exact signature and is now the create_flags=0 case of the additive v1.1 entry point shuttle_create_ex (SHUTTLE_ABI_VERSION stays 1). The C flag value is static_asserted against the C++ kFlagHugePages bit. The madvise call lives behind the platform seam in platform.hpp, the only file allowed to ifdef on platform. New test shuttle_hugepage_test (suite now 29): flag persisted and observed by a spawned opener, byte-exact transfer on a flagged channel, plain create leaves the bit clear, unknown bits masked. Asserts the flag contract only — never THP outcomes, which are kernel-policy-dependent and would flake in CI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JykzcEronyifSN4RnTgjTk
…w docs Lead the quick start with the native Linux CMake path (the production target — CI proves it on ubuntu-24.04), keeping the mac+Docker two-platform harness as the secondary block. New 'Using Shuttle in your project' section: add_subdirectory/FetchContent consumption of shuttle_c (C ABI) or shuttle_core (C++), verified by building a real consumer against the published snippet; vendoring guidance for non-CMake builds; pointer to shuttle_create_ex huge-page opt-in. Verification and Scope sections now stand alone (no links to the deleted dev-process docs); test count updated to 29; repository layout reflects docs/API.md + docs/ROADMAP.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JykzcEronyifSN4RnTgjTk
Tag pushes matching v* create a release whose notes come from the annotated tag message (--notes-from-tag), so release notes are curated at tag time and versioned in git. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JykzcEronyifSN4RnTgjTk
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refreshes the repository for users rather than its original build process, and lands the first post-1.0 feature.
What's in this PR
Cleanup — download only what's needed (
40ba6a5)PROGRESS.md(build ledger),docs/Shuttle_SRS.md,docs/Shuttle_Implementation_Plan.md,docs/SHUTTLE_AGENT_PROMPT.md. Comments inMakefile/ci.ymlthat pointed at them now carry their explanation inline..gitignoregains defensive entries (__pycache__/,target/, editor dirs,CMakeUserPresets.json).docs/API.md— consolidated C ABI reference: every function, error-code table, lifecycle/sizing rules, zero-copy borrow rules, segment layout + flags contract, liveness caveat, Python/Rust binding patterns. Closes the long-standing NFR-M2 gap.docs/ROADMAP.md— triaged upgrade directions: already shipped in v1, landing here, v1.x candidates (hugetlbfs, stats counters, opt-in backpressure policies, bare-metal benchmark), exploratory v2 (CUDA IPC, Windows).Feature — opt-in transparent huge pages (
7f03eab)shuttle_create_ex(name, capacity, max_payload, create_flags, err)withSHUTTLE_CREATE_HUGEPAGES: advises the mapping viamadvise(MADV_HUGEPAGE)on Linux (advisory; no-op on macOS/unsupported kernels; never a correctness dependency). The flag is persisted in the header's cold identity block before theinit_staterelease-store, so openers advise their own mapping too; unknown bits are masked. The frozen v1 surface is untouched (shuttle_createdelegates with flags=0;SHUTTLE_ABI_VERSIONstays 1; C/C++ flag values arestatic_assert-tied). Themadvisecall lives behind the platform seam inplatform.hpp.shuttle_hugepage_test(suite now 29): flag persisted and observed by a spawned opener, byte-exact transfer on a flagged channel, plain create leaves the bit clear, unknown bits masked. Asserts the flag contract only — never THP outcomes, which are kernel-policy-dependent and would flake in CI.README (
ef3a36e)Verification
shuttle_hugepage_testgreen under both).🤖 Generated with Claude Code
https://claude.ai/code/session_01JykzcEronyifSN4RnTgjTk