From 24f410430b33aaf1f288b83ea37e18fa959e9d3e Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 27 Oct 2026 13:30:54 +0000 Subject: docs(memory): describe standard-library allocation and explicit imports Co-Authored-By: Claude Opus 5.5 --- AGENTS/CONVENTIONS/CALLS.md | 16 +++++++++------- AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md | 6 ++++-- AGENTS/CONVENTIONS/STRINGS.md | 2 +- 3 files changed, 14 insertions(+), 10 deletions(-) (limited to 'AGENTS/CONVENTIONS') diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md index 3fc2daa..55b3647 100644 --- a/AGENTS/CONVENTIONS/CALLS.md +++ b/AGENTS/CONVENTIONS/CALLS.md @@ -32,9 +32,10 @@ bridge C void* and nominal pseudocode pointer types. An expression's expected result type filters overloads when present. Overload sets, visibility filtering and exact selection: [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution). -- In all cases, `emitPrototype` rejects names that collide with runtime/libc symbols - (`isReservedRuntimeName`), builtins, or enum values. Signatures retain the first - declaration spelling for LLVM lookup, independently of call-site casing. +- `emitPrototype` rejects builtin and enum names. Ordinary non-EXTERN, non-OVERLOAD + definitions also reject runtime/libc names (`isReservedRuntimeName`); OVERLOAD + definitions have signature-mangled symbols and cannot replace libc symbols. + Signatures retain the first declaration spelling for LLVM lookup, independently of call-site casing. - Methods use `Class.Method` names and a hidden leading receiver address; their FuncSig parameters contain only explicit source parameters. @@ -52,11 +53,12 @@ callback CodeGen injects into FunctionGen). BYVAL arrays copy their buffer at ca entry and clone STRING-bearing elements; BYREF binds the caller's buffer. **Builtins are plain identifiers backed by one table.** Builtins -(EOF/MALLOC/FREE/REALLOC) parse as ordinary calls — no lexer/parser support, and the +(EOF/INT) parse as ordinary calls — no lexer/parser support, and the names are not reserved words. The inline constexpr `Builtins` table in the internal `lib/CodeGen/Builtins.h` ({Name, Arity, ReturnTypeName}) is the single source of truth: `emitCall` checks arity against it before dispatching to the per-builtin emit branches (still an if-chain, ahead of the user-function fallback), and -`getExprTypeInfo` reads return types from it. EOF and the memory builtins consume the -call source line for runtime diagnostics; they touch mutable runtime state and can -throw. +`getExprTypeInfo` reads return types from it. EOF and INT consume the call source +line for runtime diagnostics and can throw. +MALLOC/REALLOC/FREE are ordinary OVERLOAD functions in memory.cps, with no builtin +dispatch or type rules in the compiler. diff --git a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md index deed7ec..8ee97ec 100644 --- a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md +++ b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md @@ -41,8 +41,10 @@ it only on non-library to library calls. Runtime helper line arguments use RuntimeCheck::lineValue too. Compiler diagnostics retain the owning file location. **Default standard library.** The driver extracts embedded std.cps, its imported units -and matching objects to a temporary directory that survives linking/execution. User +and matching objects to a content-keyed cache (or temporary fallback) that survives +linking/execution. User units implicitly import std.cps; normal transitive visibility applies. -no-std -suppresses all default library inputs and objects. Explicit libraries retain the +suppresses all default library inputs and objects. std.cps imports string.cps and +memory.cps; keyword NEW/DELETE require the latter even with -no-std. Explicit libraries retain the ordinary INCLUDE/command-line rules. Source files and objects are embedded by a build-time Perl generator. Saved -S output remains IR only. diff --git a/AGENTS/CONVENTIONS/STRINGS.md b/AGENTS/CONVENTIONS/STRINGS.md index 9bb81cf..d07c217 100644 --- a/AGENTS/CONVENTIONS/STRINGS.md +++ b/AGENTS/CONVENTIONS/STRINGS.md @@ -26,5 +26,5 @@ handles. Records and BYVAL arrays containing STRING recursively copy their string-bearing fields/elements; RETURN and temporary cleanup preserve ownership. C_STRING casts borrow a STRING buffer or construct an owning STRING copy in the other direction. FileHandler owns copied open-file names and frees them on close; READFILE -buffers are copied into STRING and released. Explicit MemoryHandler allocations remain +buffers are copied into STRING and released. Explicit memory-library allocations remain separate from these internal objects. -- cgit v1.3.1-4-g156e