From 4e22f464387725a5a282f3d72e11cfb694a31a5a Mon Sep 17 00:00:00 2001 From: _ov4 Date: Sat, 17 Oct 2026 05:33:33 +0000 Subject: feat(memory): add checked REALLOC with failure preservation Co-Authored-By: Claude Fable 5.1 --- doc/language/function/cpsc-function-free.7.md | 4 +-- doc/language/function/cpsc-function-malloc.7.md | 8 ++--- doc/language/function/cpsc-function-realloc.7.md | 41 ++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 doc/language/function/cpsc-function-realloc.7.md (limited to 'doc/language/function') diff --git a/doc/language/function/cpsc-function-free.7.md b/doc/language/function/cpsc-function-free.7.md index 298199d..e2c8f12 100644 --- a/doc/language/function/cpsc-function-free.7.md +++ b/doc/language/function/cpsc-function-free.7.md @@ -12,7 +12,7 @@ FREE(pointer) # DESCRIPTION -FREE is a compiler extension. Its argument and return type are C void*. Explicitly cast other pointer types to a void* alias before passing them. A null pointer is accepted and returned. A non-null pointer must be the start of an active explicit MALLOC allocation; internal STRING/ARRAY storage, stack addresses, interior addresses and already released allocations are rejected with a source-line diagnostic on stdout and an anonymous exception. +FREE is a compiler extension. Its argument and return type are C `void*`. Explicitly cast other pointer types to a `void*` alias before passing them. A null pointer is accepted and returned. A non-null pointer must be the start of an active explicit MALLOC or REALLOC allocation; internal STRING/ARRAY storage, stack addresses, interior addresses and already released allocations are rejected with a source-line diagnostic on stdout and an anonymous exception. FREE returns its input address after releasing the allocation. It does not clear the caller's variable. The returned address and all aliases are invalid for memory access. Calling FREE again on that address throws unless a subsequent allocation has reused the address. Tracking cannot distinguish stale aliases once an address is reused. @@ -29,4 +29,4 @@ FREE(Memory) # SEE ALSO -[cpsc-function-malloc(7)](cpsc-function-malloc.7.md), [cpsc-keyword-function(7)](../keyword/cpsc-keyword-function.7.md), [cpsc-keyword-try(7)](../keyword/cpsc-keyword-try.7.md). +[cpsc-function-malloc(7)](cpsc-function-malloc.7.md), [cpsc-function-realloc(7)](cpsc-function-realloc.7.md), [cpsc-keyword-function(7)](../keyword/cpsc-keyword-function.7.md), [cpsc-keyword-try(7)](../keyword/cpsc-keyword-try.7.md). diff --git a/doc/language/function/cpsc-function-malloc.7.md b/doc/language/function/cpsc-function-malloc.7.md index 742367c..909903a 100644 --- a/doc/language/function/cpsc-function-malloc.7.md +++ b/doc/language/function/cpsc-function-malloc.7.md @@ -12,11 +12,11 @@ MALLOC(bytes) # DESCRIPTION -MALLOC is a compiler extension returning a C void* to the beginning of an uninitialized allocation. The size is in bytes and accepts INTEGER or a C integer, converted to the host size_t using C integer conversion rules. Negative values are not separately rejected. MALLOC(0) returns null without allocating. A nonzero allocation failure prints the source line and reason to stdout, then throws an anonymous exception catchable with TRY/CATCH. Allocation tracking failures behave the same way. +MALLOC is a compiler extension returning a C `void*` to the beginning of an uninitialized allocation. The size is in bytes and accepts INTEGER or a C integer, converted to the host size_t using C integer conversion rules. Negative values are not separately rejected. MALLOC(0) returns null without allocating. A nonzero allocation failure prints the source line and reason to stdout, then throws an anonymous exception catchable with TRY/CATCH. Allocation tracking failures behave the same way. -Declare a void* alias with C_TYPE and explicitly cast the result to a C or pseudocode pointer before dereferencing. MALLOC does not initialize fields or call constructors; it is unrelated to the CIE class NEW construct. The caller must supply enough bytes and initialize values before reading them. User memory is not automatically released. +Declare a `void*` alias with C_TYPE and explicitly cast the result to a C or pseudocode pointer before dereferencing. MALLOC does not initialize fields or call constructors; it is unrelated to the CIE class NEW construct. The caller must supply enough bytes and initialize values before reading them. User memory is not automatically released. -Only allocations from explicit memory builtins are tracked. Internal STRING and ARRAY buffers remain outside this ownership system. Tracking validates FREE addresses, not memory accesses, bounds or stale aliases after address reuse. +Only allocations from explicit memory builtins are tracked. Internal STRING and ARRAY buffers remain outside this ownership system. Tracking validates FREE/REALLOC addresses, not memory accesses, bounds or stale aliases after address reuse. # EXAMPLE @@ -34,4 +34,4 @@ FREE(Memory) # SEE ALSO -[cpsc-function-free(7)](cpsc-function-free.7.md), [cpsc-keyword-c_type(7)](../keyword/cpsc-keyword-c_type.7.md), [cpsc-keyword-try(7)](../keyword/cpsc-keyword-try.7.md). +[cpsc-function-free(7)](cpsc-function-free.7.md), [cpsc-function-realloc(7)](cpsc-function-realloc.7.md), [cpsc-keyword-c_type(7)](../keyword/cpsc-keyword-c_type.7.md), [cpsc-keyword-try(7)](../keyword/cpsc-keyword-try.7.md). diff --git a/doc/language/function/cpsc-function-realloc.7.md b/doc/language/function/cpsc-function-realloc.7.md new file mode 100644 index 0000000..19fcfdf --- /dev/null +++ b/doc/language/function/cpsc-function-realloc.7.md @@ -0,0 +1,41 @@ +% CPSC-FUNCTION-REALLOC(7) + +# NAME + +cpsc-function-realloc - resize an explicit memory allocation + +# SYNOPSIS + +```text +REALLOC(pointer, bytes) +``` + +# DESCRIPTION + +REALLOC is a compiler extension returning C `void*`. The pointer argument must also be C `void*`; explicitly cast other pointer types. The size accepts INTEGER or a C integer and converts to host size_t, just as MALLOC does. + +A null pointer behaves as MALLOC(bytes). A non-null pointer must start an active explicit MALLOC or REALLOC allocation, even when bytes is zero. Invalid addresses print the source line and reason to stdout and throw an anonymous exception before touching the memory or allocation record. + +For a valid pointer and zero bytes, REALLOC releases the block and returns null. This rule is independent of libc's zero-size behavior. For a nonzero size, successful resizing preserves the smaller of the old and new sizes; added bytes are uninitialized. The returned address may differ from the input. Use the returned pointer afterward; previous aliases must not be used. + +On nonzero allocation failure, REALLOC prints the source line and reason and throws an anonymous exception. The original allocation and its tracking record remain valid. In `p <- REALLOC(p, bytes)`, assignment occurs only on success, so a CATCH handler can still use or release the old p. A successful resize updates the existing record without allocating a new tracking node. Internal STRING/ARRAY buffers cannot be resized with this function. + +# EXAMPLE + +```text +TYPE Raw = C_TYPE("void*") +TYPE IntPointer = ^INTEGER +DECLARE Memory : Raw +DECLARE Pointer : IntPointer +Memory <- MALLOC(8) +Pointer <- (IntPointer)Memory +Pointer^ <- 42 +Memory <- REALLOC(Memory, 16) +Pointer <- (IntPointer)Memory +OUTPUT Pointer^ +FREE(Memory) +``` + +# SEE ALSO + +[cpsc-function-malloc(7)](cpsc-function-malloc.7.md), [cpsc-function-free(7)](cpsc-function-free.7.md), [cpsc-keyword-try(7)](../keyword/cpsc-keyword-try.7.md). -- cgit v1.3.1-4-g156e