Use

"memory" use exposes raw memory bindings, cached allocation helpers, public allocation entry points, and heap-usage queries.

Allocation model

• SYNCHRONIZED reports whether the cached allocation helpers synchronize access to their reusable-block queues.
• haveSLMemoryMaxCachedSize reports whether SL_MEMORY_MAX_CACHED_SIZE is configured explicitly.
• SL_MEMORY_MAX_CACHED_SIZE is the greatest allocation size handled by the cached helpers.
• debugMemory reports whether the public allocation entry points also maintain allocation metrics.
• When debugMemory is FALSE, the public allocation entry points forward to the cached helpers. When debugMemory is TRUE, they also update allocation metrics.

Public allocation entry points

mplMalloc (size -- ptr)

Allocates one block through the module’s public allocator.

mplRealloc (newSize oldSize ptr -- newPtr)

Resizes one block through the module’s public allocator.

• The shared prefix of the old and new ranges is preserved.
• The copied byte count is min(oldSize newSize).

mplFree (size ptr --)

Releases one block previously handled by the module’s public allocator.

Example: public allocation helpers

"memory" use
"control" use

{} () {} [
  p0: 4nx mplMalloc;
  4nx 65 p0 memset drop
  p1: 8nx 4nx p0 mplRealloc;
  p1 Nat8 addressToReference new 65n8 same printStack _:;
  8nx p1 mplFree
] "main" exportFunction

Expected Output During Compilation

TRUE

Runtime example

"memory" use
"String" use
"control" use

{} Int32 {} [
  p0: 4nx mplMalloc;
  4nx 65 p0 memset drop
  p1: 8nx 4nx p0 mplRealloc;
  p1 Nat8 addressToReference new 65n8 same print
  LF print
  8nx p1 mplFree
  0
] "main" exportFunction

Expected Output

TRUE

Raw memory functions

• malloc: allocates size bytes.
• realloc: resizes one allocation.
• free: releases one allocation.
• memcpy: copies one byte range without overlap handling.
• memmove: copies one byte range with overlap handling.
• memcmp: compares two byte ranges.
• memset: fills one byte range with one byte value.

Cached allocation helpers

fastAllocate (size -- ptr)

Allocates memory, reusing cached blocks for sizes not greater than SL_MEMORY_MAX_CACHED_SIZE.

• Sizes smaller than pointer size are rounded up to pointer size.
• Requesting 0nx is invalid.

fastDeallocate (size ptr --)

Releases one block previously handled by fastAllocate or fastReallocate.

• Sizes not greater than SL_MEMORY_MAX_CACHED_SIZE return the block to the module cache.
• Larger blocks are released directly.
• size must be nonzero.

fastReallocate (newSize oldSize ptr -- newPtr)

Allocates one new block of newSize, copies the shared prefix of the old and new ranges, and releases the old block.

• The copied byte count is min(oldSize newSize).
• Both oldSize and newSize must be nonzero.

getHeapUsedSize (value -- size)

Returns the heap usage attributable to value as Natx.

• The default result is 0nx.
• For combined values, non-Ref-like fields are visited recursively and their heap usage is added.
• Fields whose schema is Ref-like are not followed recursively.

Example

"memory" use
"control" use

{} () {} [
  {a: 1i32; b: 2i32;} getHeapUsedSize printStack _:;
] "main" exportFunction

Expected Output During Compilation

0nx

Debug allocation metrics

When debugMemory is TRUE, getMemoryMetrics (-- metrics) returns one record with the current allocation accounting.

• memoryCurrentAllocationCount: current live allocation count.
• memoryTotalAllocationCount: total allocation count since program start.
• memoryCurrentAllocationSize: current live allocated byte count.
• memoryTotalAllocationSize: total allocated byte count since program start.
• memoryMaxAllocationSize: greatest live allocated byte count reached so far.
• memoryChecksum: checksum over currently live allocation addresses.

See also

• Array: Growable array.
• Owner: Ownership management and move/transfer semantics.
• Pool: Pooled storage with reusable numeric keys.
• Span: Contiguous non-owning view of items of the same schema.
• Mref: Minimal Ref type with custom semantics.