Skip to content
Thru Docs

increment_anonymous_segment_sz

View as Markdown

Overview

Section titled “Overview”

The increment_anonymous_segment_sz syscall modifies the size of an anonymous memory segment by adding or subtracting a delta value. This is useful for dynamic memory allocation and deallocation.

Syscall Code

Section titled “Syscall Code”

Code: 0x01 (TN_SYSCALL_CODE_INCREMENT_ANONYMOUS_SEGMENT_SZ)

C SDK Function

Section titled “C SDK Function”
ulong tsys_increment_anonymous_segment_sz(void* segment_addr, ulong delta, void** addr);

Arguments

Section titled “Arguments”

segment_addr · void · required*

Virtual address that identifies the anonymous segment to modify. The segment type and index are extracted from this address.

delta · ulong · required

Delta value to add to the current segment size. Can be positive (expand) or negative (shrink). If zero, returns the current segment boundary address without modification.

addr · void · required**

Pointer to store the resulting segment boundary address.

Return Value

Section titled “Return Value”

Returns a syscall result code:

Success · ulong

  • TN_VM_SYSCALL_SUCCESS (0) - Operation completed successfully

Error Codes · ulong

  • TN_VM_ERR_SYSCALL_INVALID_SEGMENT_ID (-21) - Invalid segment type or index
  • TN_VM_ERR_SYSCALL_INVALID_SEGMENT_SIZE (-28) - Size overflow/underflow detected
  • TN_VM_ERR_SYSCALL_INSUFFICIENT_PAGES (-26) - Not enough free pages for expansion
  • TN_VM_ERR_SYSCALL_UNFREEABLE_PAGE (-29) - Cannot free pages when shrinking

Resource Consumption

Section titled “Resource Consumption”

Compute Units

Section titled “Compute Units”
  • Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
  • Delta cost: Additional units based on delta value
    • Positive delta: Additional units equal to the delta value
    • Negative delta: No additional cost beyond base
    • Zero delta: No additional cost (query operation)
  • Total formula: base_cost + max(0, delta)

Memory Pages

Section titled “Memory Pages”
  • Page allocation: New pages allocated from transaction pool when expanding
  • Page deallocation: Freed pages returned to transaction pool when shrinking
  • Page constraints: Pages can only be freed if allocated in current or later call frames

Side Effects

Section titled “Side Effects”
  • Memory allocation/deallocation: Pages allocated when expanding or freed when shrinking
  • Output parameter: Sets the addr parameter to the segment boundary address
  • Segment state: Updates segment size and page mappings

Usage Notes

Section titled “Usage Notes”
  • When delta is 0, returns current segment size without modification
  • For positive delta: allocates new pages and returns old boundary
  • For negative delta: frees pages and returns new boundary
  • Overflow/underflow protection prevents invalid size calculations
  • Only works with anonymous data segments (heap and stack types)

Example

Section titled “Example”
#include <thru-sdk/c/tn_sdk_syscall.h>


// Increase heap segment by 4096 bytes
void* segment_addr = TSDK_ADDR(TSDK_SEG_TYPE_HEAP, 0, 0);
void* boundary_addr;
ulong result = tsys_increment_anonymous_segment_sz(segment_addr, 4096, &boundary_addr);


if (result == TN_VM_SYSCALL_SUCCESS) {
    // boundary_addr now contains the address of the old segment boundary
    // Segment has been expanded by 4096 bytes
}


// Check current size without modification
result = tsys_increment_anonymous_segment_sz(segment_addr, 0, &boundary_addr);
// boundary_addr contains current segment boundary address