dea_rt.h

dea_rt.h

Source: compiler/shared/runtime/dea_rt.h Language: C

Public L0 C runtime interface.

This header contains the declaration-only C interoperability surface for Dea/L0. Additional C translation units should include this header rather than l0_runtime.h , whose implementation definitions are owned by the single generated L0 translation unit.

The dea_* names and public signatures that do not mention level-mangled records form the source-compatible subset shared with L1. The existing l0_* names remain available for L0-specific C code. This source compatibility does not make L0 and L1 runtime binaries interchangeable.

Imports / Includes

  • stddef.h
  • stdint.h

Symbols

Macro L0_STRING_K_STATIC

1

L0_STRING_K_STATIC

Macro L0_STRING_K_HEAP

1

L0_STRING_K_HEAP

Macro DEA_STRING_K_STATIC

1

DEA_STRING_K_STATIC

Macro DEA_STRING_K_HEAP

1

DEA_STRING_K_HEAP

Macro L0_STRING_EMPTY

1

L0_STRING_EMPTY

Typed empty static string value.

Macro L0_STRING_CONST

1

L0_STRING_CONST

Static string initializer for constant byte storage.

Macro DEA_STRING_EMPTY

1

DEA_STRING_EMPTY

Macro DEA_STRING_CONST

1

DEA_STRING_CONST

Macro L0_OPT_BOOL_DEFINED

1

L0_OPT_BOOL_DEFINED

Macro L0_OPT_BYTE_DEFINED

1

L0_OPT_BYTE_DEFINED

Macro L0_OPT_INT_DEFINED

1

L0_OPT_INT_DEFINED

Macro L0_OPT_STRING_DEFINED

1

L0_OPT_STRING_DEFINED

Macro DEA_OPT_BOOL_DEFINED

1

DEA_OPT_BOOL_DEFINED

Macro DEA_OPT_BYTE_DEFINED

1

DEA_OPT_BYTE_DEFINED

Macro DEA_OPT_INT_DEFINED

1

DEA_OPT_INT_DEFINED

Macro DEA_OPT_STRING_DEFINED

1

DEA_OPT_STRING_DEFINED

Macro L0_OPT_STRING_NULL

1

L0_OPT_STRING_NULL

Macro L0_OPT_STRING_EMPTY

1

L0_OPT_STRING_EMPTY

Macro DEA_OPT_STRING_NULL

1

DEA_OPT_STRING_NULL

Macro DEA_OPT_STRING_EMPTY

1

DEA_OPT_STRING_EMPTY

Macro L0_DEFINED_l0_sys_rt_RtTimeParts

1

L0_DEFINED_l0_sys_rt_RtTimeParts

Runtime time snapshot returned through the L0 sys.rt boundary.

Macro L0_DEFINED_l0_sys_rt_RtFileInfo

1

L0_DEFINED_l0_sys_rt_RtFileInfo

Runtime filesystem metadata returned through the L0 sys.rt boundary.

Type Alias l0_bool

1

typedef uint8_t l0_bool

Type Alias l0_tiny

1

typedef int8_t l0_tiny

Reserved for future L0 language use.

Type Alias l0_short

1

typedef int16_t l0_short

Type Alias l0_int

1

typedef int32_t l0_int

Type Alias l0_long

1

typedef int64_t l0_long

Type Alias l0_byte

1

typedef uint8_t l0_byte

Type Alias l0_ushort

1

typedef uint16_t l0_ushort

Type Alias l0_uint

1

typedef uint32_t l0_uint

Type Alias l0_ulong

1

typedef uint64_t l0_ulong

Type Alias l0_float

1

typedef float l0_float

Type Alias l0_double

1

typedef double l0_double

Type Alias dea_bool

1

typedef l0_bool dea_bool

Type Alias dea_tiny

1

typedef l0_tiny dea_tiny

Type Alias dea_short

1

typedef l0_short dea_short

Type Alias dea_int

1

typedef l0_int dea_int

Type Alias dea_long

1

typedef l0_long dea_long

Type Alias dea_byte

1

typedef l0_byte dea_byte

Type Alias dea_ushort

1

typedef l0_ushort dea_ushort

Type Alias dea_uint

1

typedef l0_uint dea_uint

Type Alias dea_ulong

1

typedef l0_ulong dea_ulong

Type Alias dea_float

1

typedef l0_float dea_float

Type Alias dea_double

1

typedef l0_double dea_double

Type Alias dea_string

1

typedef l0_string dea_string

Type Alias dea_opt_bool

1

typedef l0_opt_bool dea_opt_bool

Type Alias dea_opt_byte

1

typedef l0_opt_byte dea_opt_byte

Type Alias dea_opt_int

1

typedef l0_opt_int dea_opt_int

Type Alias dea_opt_string

1

typedef l0_opt_string dea_opt_string

Function rt_strlen

1

dea_int rt_strlen(dea_string str)

Return the length of a string in bytes.

Parameters:

  • str: String value.

Returns: String length.

Function rt_string_get

1

dea_byte rt_string_get(dea_string s, dea_int index)

Return the byte at a string index.

Parameters:

  • s: String value.
  • index: Byte index.

Returns: Byte at index.

Function rt_string_bytes_ptr

1

dea_byte * rt_string_bytes_ptr(dea_string s)

Return a pointer to the raw byte data of a string.

The returned storage is runtime-managed and read-only to checked generated L0 code. It must not be passed to drop or rt_free .

Parameters:

  • s: String value.

Returns: Pointer to the first byte.

Function rt_string_equals

1

dea_bool rt_string_equals(dea_string a, dea_string b)

Return whether two strings contain equal bytes.

Parameters:

  • a: First string.
  • b: Second string.

Returns: Nonzero when the strings are equal.

Function rt_string_compare

1

dea_int rt_string_compare(dea_string a, dea_string b)

Compare two strings lexicographically by byte value.

Parameters:

  • a: First string.
  • b: Second string.

Returns: Negative when a < b, zero when equal, or positive when a > b.

Function rt_string_concat

1

dea_string rt_string_concat(dea_string a, dea_string b)

Concatenate two strings.

Parameters:

  • a: First string.
  • b: Second string.

Returns: Newly allocated concatenated string.

Function rt_string_slice

1

dea_string rt_string_slice(dea_string s, dea_int start, dea_int end)

Return a byte slice of a string.

Parameters:

  • s: Source string.
  • start: Inclusive start index.
  • end: Exclusive end index.

Returns: Newly allocated string slice.

Function rt_string_from_byte

1

dea_string rt_string_from_byte(dea_byte b)

Create a string from one byte.

Parameters:

  • b: Byte value.

Returns: Newly allocated one-byte string.

Function rt_string_from_byte_array

1

dea_string rt_string_from_byte_array(dea_byte *bytes, dea_int len)

Create a string from a byte array.

Parameters:

  • bytes: Pointer to the byte array.
  • len: Number of bytes.

Returns: Newly allocated string containing the provided bytes.

Function rt_string_retain

1

void rt_string_retain(dea_string s)

Increment the reference count of a heap string.

This is a no-op for static or non-reference-counted strings.

Parameters:

  • s: String to retain.

Function rt_string_release

1

void rt_string_release(dea_string s)

Decrement the reference count of a heap string and free it at zero.

This is a no-op for static or non-reference-counted strings.

Parameters:

  • s: String to release.

Function rt_system

1

dea_int rt_system(dea_string cmd)

Execute a system command and return its normalized status.

Parameters:

  • cmd: Command string.

Returns: Command exit code, 128 + signal for signal termination, or a negative value when the shell could not be launched.

Function rt_get_env_var

1

dea_opt_string rt_get_env_var(dea_string name)

Return the value of an environment variable.

Parameters:

  • name: Environment variable name.

Returns: Variable value, or an empty optional when it is unset or invalid.

Function rt_get_argc

1

dea_int rt_get_argc(void)

Return the number of process arguments.

Returns: Argument count.

Function rt_get_pid

1

dea_int rt_get_pid(void)

Return the current process identifier.

Returns: Process identifier.

Function rt_get_argv

1

dea_string rt_get_argv(dea_int i)

Return one process argument.

Parameters:

  • i: Argument index.

Returns: Static string view of the selected argument.

Function rt_time_unix

1

dea_bool rt_time_unix(struct l0_sys_rt_RtTimeParts *out)

Capture current Unix wall time.

Parameters:

  • out: Time record to populate.

Returns: Nonzero on success.

Function rt_time_monotonic

1

dea_bool rt_time_monotonic(struct l0_sys_rt_RtTimeParts *out)

Capture current monotonic time.

Parameters:

  • out: Time record to populate.

Returns: Nonzero on success.

Function rt_time_monotonic_supported

1

dea_bool rt_time_monotonic_supported(void)

Return whether the runtime supports a monotonic clock.

Returns: Nonzero when supported.

Function rt_time_local_offset_sec

1

dea_opt_int rt_time_local_offset_sec(dea_int unix_sec)

Return the local UTC offset for a Unix timestamp.

Parameters:

  • unix_sec: Unix timestamp in seconds.

Returns: Offset in seconds, or an empty optional on error.

Function rt_time_local_is_dst

1

dea_opt_bool rt_time_local_is_dst(dea_int unix_sec)

Return whether local time is in daylight-saving time.

Parameters:

  • unix_sec: Unix timestamp in seconds.

Returns: DST state, or an empty optional on error.

Function rt_read_file_all

1

dea_opt_string rt_read_file_all(dea_string path)

Read an entire file into a string.

Parameters:

  • path: File path.

Returns: File contents, or an empty optional on error.

Function rt_write_file_all

1

dea_bool rt_write_file_all(dea_string path, dea_string data)

Write a string completely to a file.

Parameters:

  • path: File path.
  • data: String contents.

Returns: Nonzero on success.

Function rt_file_info

1

struct l0_sys_rt_RtFileInfo rt_file_info(dea_string path)

Return basic metadata for a path.

Parameters:

  • path: Filesystem path.

Returns: File metadata with optional size and timestamp fields.

Function rt_delete_file

1

dea_bool rt_delete_file(dea_string path)

Delete a file.

Parameters:

  • path: File path.

Returns: Nonzero on success.

Function rt_stdin_read

1

dea_int rt_stdin_read(dea_byte *buf, dea_int capacity)

Read bytes from standard input.

Parameters:

  • buf: Destination buffer.
  • capacity: Maximum number of bytes to read.

Returns: Bytes read, zero on EOF, or -1 on error.

Function rt_stdout_write

1

dea_int rt_stdout_write(dea_byte *buf, dea_int len)

Write bytes to standard output.

Parameters:

  • buf: Source buffer.
  • len: Maximum number of bytes to write.

Returns: Bytes written, or -1 on error.

Function rt_stderr_write

1

dea_int rt_stderr_write(dea_byte *buf, dea_int len)

Write bytes to standard error.

Parameters:

  • buf: Source buffer.
  • len: Maximum number of bytes to write.

Returns: Bytes written, or -1 on error.

Function rt_flush_stdout

1

void rt_flush_stdout(void)

Flush the standard output buffer.

Function rt_flush_stderr

1

void rt_flush_stderr(void)

Flush the standard error buffer.

Function rt_print

1

void rt_print(dea_string s)

Print a string to standard output without a newline.

Parameters:

  • s: String to print.

Function rt_print_stderr

1

void rt_print_stderr(dea_string s)

Print a string to standard error without a newline.

Parameters:

  • s: String to print.

Function rt_println

1

void rt_println(void)

Print a newline to standard output.

Function rt_println_stderr

1

void rt_println_stderr(void)

Print a newline to standard error.

Function rt_print_int

1

void rt_print_int(dea_int x)

Print an integer to standard output.

Parameters:

  • x: Integer to print.

Function rt_print_int_stderr

1

void rt_print_int_stderr(dea_int x)

Print an integer to standard error.

Parameters:

  • x: Integer to print.

Function rt_print_bool

1

void rt_print_bool(dea_bool x)

Print a boolean to standard output.

Parameters:

  • x: Boolean to print.

Function rt_print_bool_stderr

1

void rt_print_bool_stderr(dea_bool x)

Print a boolean to standard error.

Parameters:

  • x: Boolean to print.

Function rt_read_line

1

dea_opt_string rt_read_line(void)

Read one line from standard input.

Returns: Line without the trailing newline, or an empty optional at EOF.

Function rt_read_char

1

dea_int rt_read_char(void)

Read one byte from standard input.

Returns: Byte value, or -1 at EOF or on error.

Function rt_abort

1

void rt_abort(dea_string message)

Abort execution with a message.

Parameters:

  • message: Abort message.

Function rt_exit

1

void rt_exit(dea_int code)

Exit the process with a status code.

Parameters:

  • code: Exit status.

Function rt_srand

1

void rt_srand(dea_int seed)

Seed the runtime pseudo-random number generator.

Parameters:

  • seed: Integer seed.

Function rt_rand

1

dea_int rt_rand(dea_int max)

Return a pseudo-random integer below an upper bound.

Parameters:

  • max: Exclusive upper bound.

Returns: Random integer in [0, max).

Function rt_errno

1

dea_int rt_errno(void)

Return the current C runtime error number.

Returns: Current errno value.

Function rt_alloc

1

void * rt_alloc(dea_int bytes)

Allocate raw memory.

Parameters:

  • bytes: Number of bytes to allocate; must be positive.

Returns: Allocated pointer, or NULL on allocation failure.

Function rt_realloc

1

void * rt_realloc(void *ptr, dea_int new_bytes)

Resize a raw runtime allocation.

If ptr is NULL , this behaves like rt_alloc . Checked builds reject pointers owned by new , ARC strings, static strings, or foreign storage.

Parameters:

  • ptr: Existing raw allocation, or NULL.
  • new_bytes: New positive size in bytes.

Returns: Resized pointer, or NULL on allocation failure.

Function rt_free

1

void rt_free(void *ptr)

Free a raw runtime allocation.

Parameters:

  • ptr: Pointer returned by rt_alloc, rt_calloc, or rt_realloc.

Function rt_calloc

1

void * rt_calloc(dea_int count, dea_int elem_size)

Allocate zero-initialized raw memory.

Parameters:

  • count: Positive element count.
  • elem_size: Positive element size in bytes.

Returns: Allocated pointer, or NULL on allocation failure.

Function rt_memset

1

void * rt_memset(void *dest, dea_int value, dea_int bytes)

Fill a memory region with one byte value.

Parameters:

  • dest: Destination pointer.
  • value: Byte value, converted as by C memset.
  • bytes: Number of bytes.

Returns: dest.

Function rt_memcpy

1

void * rt_memcpy(void *dest, void *src, dea_int bytes)

Copy bytes between non-overlapping memory regions.

Parameters:

  • dest: Destination pointer.
  • src: Source pointer.
  • bytes: Number of bytes.

Returns: dest.

Function _rt_byte_span_offset

1

dea_int _rt_byte_span_offset(void *base, dea_int span_bytes, void *candidate)

Return a candidate address’s offset within a half-open byte span.

This implementation-private helper is used by the bundled standard library and is not part of the stable public runtime API.

Parameters:

  • base: Base address of the byte span.
  • span_bytes: Positive byte extent of the span.
  • candidate: Address to classify.

Returns: Byte offset within the span, or -1 when not contained.

Function _rt_byte_spans_overlap

1

dea_bool _rt_byte_spans_overlap(void *first, dea_int first_bytes, void *second, dea_int second_bytes)

Return whether two positive half-open byte spans overlap.

This implementation-private helper is used by the bundled standard library and is not part of the stable public runtime API.

Parameters:

  • first: Base address of the first byte span.
  • first_bytes: Byte extent of the first span.
  • second: Base address of the second byte span.
  • second_bytes: Byte extent of the second span.

Returns: Non-zero when the spans overlap.

Function rt_memcmp

1

dea_int rt_memcmp(void *a, void *b, dea_int bytes)

Compare two memory regions.

Parameters:

  • a: First pointer.
  • b: Second pointer.
  • bytes: Number of bytes.

Returns: Negative, zero, or positive according to byte ordering.

Function rt_array_element

1

void * rt_array_element(void *array_data, dea_int element_size, dea_int index)

Return a pointer to an array element.

Parameters:

  • array_data: Array base pointer.
  • element_size: Positive element size in bytes.
  • index: Non-negative element index.

Returns: Pointer to the selected element.

Function rt_register_foreign

1

void rt_register_foreign(void *ptr, dea_int bytes, dea_bool read_only)

Register externally owned storage with the checked pointer runtime.

Repeating an identical live registration is a no-op. Registration does not transfer ownership; unregister the range before its external lifetime ends.

Parameters:

  • ptr: Exact storage base pointer.
  • bytes: Positive accessible extent in bytes.
  • read_only: Whether checked writes must be rejected.

Function rt_unregister_foreign

1

void rt_unregister_foreign(void *ptr)

Remove a foreign-storage registration without freeing its payload.

Parameters:

  • ptr: Exact base pointer passed to rt_register_foreign.

Function rt_hash_bool

1

dea_int rt_hash_bool(dea_bool value)

Hash a boolean value.

Parameters:

  • value: Boolean value.

Returns: 32-bit hash.

Function rt_hash_byte

1

dea_int rt_hash_byte(dea_byte value)

Hash a byte value.

Parameters:

  • value: Byte value.

Returns: 32-bit hash.

Function rt_hash_int

1

dea_int rt_hash_int(dea_int value)

Hash an integer value.

Parameters:

  • value: Integer value.

Returns: 32-bit hash.

Function rt_hash_string

1

dea_int rt_hash_string(dea_string value)

Hash a string value.

Parameters:

  • value: String value.

Returns: 32-bit hash.

Function rt_hash_data

1

dea_int rt_hash_data(void *data, dea_int size)

Hash raw bytes.

Parameters:

  • data: Data pointer.
  • size: Number of bytes.

Returns: 32-bit hash.

Function rt_hash_opt_bool

1

dea_int rt_hash_opt_bool(dea_opt_bool opt)

Hash an optional boolean value.

Parameters:

  • opt: Optional boolean.

Returns: 32-bit hash.

Function rt_hash_opt_byte

1

dea_int rt_hash_opt_byte(dea_opt_byte opt)

Hash an optional byte value.

Parameters:

  • opt: Optional byte.

Returns: 32-bit hash.

Function rt_hash_opt_int

1

dea_int rt_hash_opt_int(dea_opt_int opt)

Hash an optional integer value.

Parameters:

  • opt: Optional integer.

Returns: 32-bit hash.

Function rt_hash_opt_string

1

dea_int rt_hash_opt_string(dea_opt_string opt)

Hash an optional string value with presence-sensitive domain separation.

Parameters:

  • opt: Optional string.

Returns: 32-bit hash.

Function rt_hash_ptr

1

dea_int rt_hash_ptr(void *ptr)

Hash a pointer address.

Parameters:

  • ptr: Non-null pointer.

Returns: 32-bit hash.

Function rt_hash_opt_ptr

1

dea_int rt_hash_opt_ptr(void *opt)

Hash an optional pointer address.

Parameters:

  • opt: Non-null optional pointer representation.

Returns: 32-bit hash.

Struct _l0_h_string

Heap-allocated L0 string header.

Member Data _l0_h_string::refcount

1

l0_int refcount

Member Data _l0_h_string::len

1

l0_int len

Member Data _l0_h_string::bytes

1

char bytes

Struct l0_string

Unified L0 string value: static bytes or one heap string header.

Member Data l0_string::kind

1

unsigned int kind: 1

Member Data l0_string::int

1

unsigned int: 0

Member Data l0_string::len

1

l0_int len

Member Data l0_string::bytes

1

const char* bytes

Member Data l0_string::s_str

1

struct l0_string s_str

Member Data l0_string::h_str

1

_l0_h_string* h_str

Member Data l0_string::data

1

union l0_string data

Struct l0_opt_bool

Member Data l0_opt_bool::has_value

1

l0_bool has_value

Member Data l0_opt_bool::value

1

l0_bool value

Struct l0_opt_byte

Member Data l0_opt_byte::has_value

1

l0_bool has_value

Member Data l0_opt_byte::value

1

l0_byte value

Struct l0_opt_int

Member Data l0_opt_int::has_value

1

l0_bool has_value

Member Data l0_opt_int::value

1

l0_int value

Struct l0_opt_string

Member Data l0_opt_string::has_value

1

l0_bool has_value

Member Data l0_opt_string::value

1

l0_string value

Struct l0_sys_rt_RtTimeParts

Member Data l0_sys_rt_RtTimeParts::sec

1

l0_int sec

Member Data l0_sys_rt_RtTimeParts::nsec

1

l0_int nsec

Struct l0_sys_rt_RtFileInfo

Member Data l0_sys_rt_RtFileInfo::exists

1

l0_bool exists

Member Data l0_sys_rt_RtFileInfo::is_file

1

l0_bool is_file

Member Data l0_sys_rt_RtFileInfo::is_dir

1

l0_bool is_dir

Member Data l0_sys_rt_RtFileInfo::size

1

l0_opt_int size

Member Data l0_sys_rt_RtFileInfo::mtime_sec

1

l0_opt_int mtime_sec

Member Data l0_sys_rt_RtFileInfo::mtime_nsec

1

l0_opt_int mtime_nsec