Skip to content

Runtime Module Contracts

Every target maps one source module to the logical RUNTIME module. That module supplies reserved declarations used to implement language operations; application modules cannot redeclare them. Application source normally uses ASSERT, PANIC, NEW, DELETE, global objects, and VAR PER_THREAD while the compiler connects those features to the contracts on this page.

Diagnostics

Runtime assertion and panic handling use fixed named-parameter signatures:

::ASSERT_FAIL FUNCTION(
  @expr STRING_CONSTANT,
  @file SZ,
  @line SZ,
  @column SZ,
  @tag CONST->STRING_CONSTANT
)
{
  UNIMPLEMENTED;
}

::PANIC FUNCTION(
  @message STRING_CONSTANT,
  @file SZ,
  @line SZ,
  @column SZ
)
{
  UNIMPLEMENTED;
}

ASSERT_FAIL receives the source expression text, source-file index, line, column, and optional assertion tag. PANIC receives the message and source position. These functions must not return to the failed source path.

On Windows native targets, ::CHECK_STACK is an architecture-specific ASM_PROCEDURE used for stack probing. A Windows LLVM output that needs the probe requires that declaration in RUNTIME.

Square root

SQRT(value) accepts a floating-point argument and returns the same type. The result is rounded to that format using round-to-nearest, ties-to-even. Signed zero and positive infinity are preserved. Negative nonzero values and NaNs produce canonical NaN. The argument is evaluated once.

The runtime provides a generic fallback with the following signature:

::SQRT FUNCTION(@ARG:value AUTO_FLOAT(total, exponent)):
  FLOAT(total, exponent)

The compiler resolves the fallback through ordinary function overload resolution. Its return type must match the argument type. The supplied runtime uses integer square-root iteration and exact remainders, including for subnormal inputs and subnormal results. The algorithm supports arbitrary binary formats; native execution remains subject to backend representation support.

The LLVM backend substitutes hardware square root only for recognized formats and CPU features: binary32 with x86 SSE, binary64 with x86 SSE2, and binary32 or binary64 with ARM64 floating-point support. Other configurations retain the runtime implementation. Baseline x86 x87 evaluation is excluded because extended-precision evaluation can introduce double rounding.

Exception handling

The runtime supplies EXCEPTION_PTR, CURRENT_EXCEPTION(), and THROW_EXCEPTION_PTR(@exception handle), together with exception-object ownership and native propagation. The reserved handle type has a postfix ?? presence test, IS_OUT_OF_MEMORY() sentinel detection, and identity equality; it exposes no reference-count query.

Native targets use the Quxlang unwinder. Exception storage allocation failure selects the permanent UNWIND_OUT_OF_MEMORY sentinel. Compiler-provided POLYMORPHIC_BASE supplies the universal polymorphic view independently of the runtime module's declarations. Application semantics and current target limits are specified in Exception Handling.

Default allocator

NEW and DELETE resolve typed storage through RUNTIME_MODULE::DEFAULT_ALLOCATOR#(T). The default allocator supplies these language integration members:

::ALLOC FUNCTION(): ->TYPED_STORAGE(T);
::DEALLOC FUNCTION(@PTR:ptr ->TYPED_STORAGE(T));
::MULTI_ALLOC FUNCTION(@COUNT:count SZ): =>>TYPED_STORAGE(T);
::MULTI_DEALLOC FUNCTION(@PTR:ptr =>>TYPED_STORAGE(T), @COUNT:count SZ);

The allocator returns uninitialized storage for the selected element type. COUNT selects MULTI_ALLOC and MULTI_DEALLOC, including counts zero and one. Array storage must be contiguous and correctly aligned for the element type. The allocation implementation checks size overflow and reports allocation failure through the runtime's ordinary exception contract. Deallocation receives the original pointer and evaluated count.

WITH(allocator) selects typed ALLOCATE#T and DEALLOCATE#T members through ordinary member lookup. Scalar allocation passes no count; counted allocation passes @COUNT. Deallocation passes @PTR, and counted deallocation additionally passes @COUNT. Class members and receiver-bound members use the same contracts.

Construction starts after allocation. If element construction fails, ordinary function cleanup destroys the current output and partial subobjects. The array initializer destroys its completed prefix in reverse order and calls the matching deallocation operation once. Successful deletion destroys the elements before releasing their storage.

The runtime may select compile-time, native, and managed implementations with RUNTIME CONSTEXPR, RUNTIME NATIVE, and target predicates. Native allocators provide native storage, while the JVM path uses managed object-storage builtins.

Global initialization guards

The runtime module alone may name INITGUARD. It supplies three operations for thread-safe initialization of nontrivial global objects:

::INITGUARD_TRY_ACQUIRE FUNCTION(@guard MUT& INITGUARD): BOOL
{
  UNIMPLEMENTED;
}

::INITGUARD_COMPLETE FUNCTION(@guard MUT& INITGUARD)
{
  UNIMPLEMENTED;
}

::INITGUARD_ABORT FUNCTION(@guard MUT& INITGUARD)
{
  UNIMPLEMENTED;
}

INITGUARD_TRY_ACQUIRE returns TRUE to the caller responsible for initialization and FALSE once the object is already initialized. Contending callers wait for that decision. The successful path completes the guard after construction; a failed or unwinding path aborts it so a later attempt can retry.

These declarations are runtime hooks. Application source declares the global object and does not manipulate its guard directly.

Per-thread initialization and destruction

Nontrivial VAR PER_THREAD objects use the corresponding per-thread contract:

::thread_destructor_node STRUCT
{
  .next VAR MUT->thread_destructor_node;
  .deinitializer VAR CONST->PROCEDURE();
  .guard VAR MUT->INITGUARD;
}

::THREAD_INITGUARD_TRY_ACQUIRE
  FUNCTION(@guard MUT& INITGUARD): BOOL
{
  UNIMPLEMENTED;
}

::THREAD_DESTRUCTOR_REGISTER FUNCTION(
  @node MUT& thread_destructor_node,
  @guard MUT& INITGUARD,
  @deinitializer CONST->PROCEDURE()
)
{
  UNIMPLEMENTED;
}

The per-thread acquire operation distinguishes uninitialized, initialized, recursively initializing, and destroyed states. After successful construction, registration adds the object's deinitializer to the current thread. The runtime drains registered destructors in reverse completion order and marks their guards destroyed.

The current runtime also reserves ::THREAD_RUNTIME_START and ::THREAD_FINISH as the entry and exit boundary for a Quxlang-managed thread. They expose operations that establish thread identity and drain per-thread lifetime before native thread teardown; a platform integration may call that boundary when it creates or finishes a managed thread.

::THREAD_RUNTIME_START FUNCTION(@identity MUT->thread_identity)
{
  UNIMPLEMENTED;
}

::THREAD_FINISH FUNCTION()
{
  UNIMPLEMENTED;
}

Startup and test entrypoints

::PROGRAM_START, ::POST_DETECT, and ::UNIT_TEST_MAIN are also reserved to the runtime module. Their signatures, stepping tables, and dispatch order are documented on Program startup and runtime hooks. Runtime CPU detector declarations use the reserved ::DETECT_<capability> names described on CPU capabilities and steppings.

See NEW and DELETE, Thread-Local Variables, and Diagnostics and explicit failure.

Test and arithmetic failures

The runtime owns the TEST_FAILED and ARITHMETIC_OVERFLOW exception types. TEST_EXPECT calls THROW_TEST_FAILED(@EXPR text, @TAG tag) with STRING_CONSTANT arguments. Checked arithmetic calls THROW_ARITHMETIC_OVERFLOW(); failed assumed-in-range arithmetic with checks enabled calls PANIC_ARITHMETIC_OVERFLOW(). These functions terminate the failed path by throwing or panicking as indicated. The exception types and hooks are reserved runtime declarations.