Runtime Lifecycle

Functions
uint32_t	detlef_abi_version (void)
DetlefRuntime *	detlef_runtime_new (void)
void	detlef_runtime_free (DetlefRuntime *runtime)
void	detlef_text_free (DetlefText text)
DetlefStatus	detlef_runtime_access (DetlefRuntime *runtime, DetlefAccessCallback callback, void *user_data)
DetlefStatus	detlef_last_error (DetlefRuntime *runtime, DetlefText *error)
DetlefStatus	detlef_runtime_load_package (DetlefRuntime *runtime, DetlefSlice archive)
DetlefStatus	detlef_native_target (DetlefText *out)

Detailed Description

Function Documentation

detlef_abi_version()

uint32_t detlef_abi_version

(

void

)

Read the experimental native ABI version. A matching version must be checked before using a separately compiled package; it is not automatic compatibility negotiation.

Returns

The ABI version, currently 4.

detlef_last_error()

DetlefStatus detlef_last_error	(	DetlefRuntime *	runtime,
		DetlefText *	error
	)

Copy the last runtime diagnostic without clearing it. Busy and invalid-argument statuses need not set a new diagnostic.

Parameters

	runtime	Borrowed live runtime.
[out]	error	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free(). Must not already own unreleased text.

Returns

DETLEF_OK on success, otherwise an error status.

detlef_native_target()

DetlefStatus detlef_native_target

(

DetlefText *

out

)

Read the native target triple used to select archive artifacts.

Parameters

[out]

out

Receives owned UTF-8 target text. Must be freed once with detlef_text_free().

Returns

DETLEF_OK on success, otherwise an error status.

detlef_runtime_access()

DetlefStatus detlef_runtime_access	(	DetlefRuntime *	runtime,
		DetlefAccessCallback	callback,
		void *	user_data
	)

Invoke a synchronous setup callback immediately with borrowed context access. The callback is not registered for later execution.

Parameters

runtime	Borrowed live runtime, which must not already be executing.
callback	Synchronous callback. Access expires on return and must not be saved or freed.
user_data	Borrowed callback data, valid through the invocation. Never freed by DETLEF.

Returns

DETLEF_OK on success; DETLEF_BUSY on reentry; otherwise an error status. The callback result is a status, not a value handle.

detlef_runtime_free()

void detlef_runtime_free

(

DetlefRuntime *

runtime

)

Destroy a runtime, its remaining handles, callbacks, and loaded package state. Must not be called while the runtime or one of its callbacks is active.

Parameters

runtime

Owned runtime to destroy. NULL has no effect. The pointer and its handles must not be used afterwards.

detlef_runtime_load_package()

DetlefStatus detlef_runtime_load_package	(	DetlefRuntime *	runtime,
		DetlefSlice	archive
	)

Load a trusted native .dtfpkg archive from a UTF-8 filesystem path and initialize its registrations. The library and state remain loaded until runtime destruction, including after partial initialization failure. Loading a duplicate package name fails.

Parameters

runtime	Borrowed idle runtime.
archive	Borrowed UTF-8 archive path. File access and native code loading occur immediately.

Returns

DETLEF_OK after initialization, otherwise an error status. Earlier registrations are not rolled back on failure.

detlef_runtime_new()

DetlefRuntime * detlef_runtime_new

(

void

)

Create a bare runtime without stdlib. It must remain on its creating thread.

Returns

An owned runtime, which must be destroyed once with detlef_runtime_free(); NULL if creation panics.

detlef_text_free()

void detlef_text_free

(

DetlefText

text

)

Free one unchanged owned text buffer using the runtime allocator. Copying a DetlefText struct does not create a second owned buffer.

Parameters

text	Owned text to free exactly once. Must not be passed to C free() or freed twice.