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:
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.