base.h File Reference

Base types, descriptors, spans, and host allocation helpers. More...

Go to the source code of this file.

Data Structures
struct	loomc_string_view_t
	Non-owning string view over bytes that need not be NUL-terminated. More...
struct	loomc_byte_span_t
	Non-owning view over immutable bytes. More...
struct	loomc_dimension3_t
	Three-dimensional unsigned extent used by Loom C API structs. More...
struct	loomc_option_entry_t
	One loose string option entry. More...
struct	loomc_option_dict_t
	Ordered loose string option dictionary. More...
struct	loomc_allocator_alloc_params_t
	Allocation parameters passed to loomc_allocator_ctl_fn_t callbacks. More...
struct	loomc_allocator_t
	Host allocator used for persistent Loom object storage. More...

Macros
#define	LOOMC_API_EXPORT
	Exports a public Loom C API symbol from a shared library build.
#define	LOOMC_API_PTR
	Marks a public callback function pointer type.
#define	LOOMC_HOST_SIZE_MAX   ((loomc_host_size_t)(SIZE_MAX))
	Largest representable loomc_host_size_t value.
#define	IREE_ALLOCATOR_ALLOC_PARAMS_T_DEFINED_
	Indicates that the shared allocator parameter structure has been declared.

Typedefs
typedef size_t	loomc_host_size_t
	Host allocation and container size type.
typedef struct iree_status_handle_t *	loomc_status_t
	Opaque status handle.
typedef uint32_t	loomc_allocator_command_t
	Controls the behavior of a loomc_allocator_ctl_fn_t callback.
typedef loomc_status_t(*	loomc_allocator_ctl_fn_t) (void *self, loomc_allocator_command_t command, const void *params, void **inout_ptr)
	Host allocation control callback.

Enumerations
enum	loomc_structure_type_t {   LOOMC_STRUCTURE_TYPE_NONE = 0 , LOOMC_STRUCTURE_TYPE_SOURCE_OPTIONS = 1 , LOOMC_STRUCTURE_TYPE_WORKSPACE_OPTIONS = 2 , LOOMC_STRUCTURE_TYPE_CONTEXT_OPTIONS = 3 ,   LOOMC_STRUCTURE_TYPE_LINK_INDEX_BUILDER_OPTIONS = 4 , LOOMC_STRUCTURE_TYPE_LINKER_OPTIONS = 5 , LOOMC_STRUCTURE_TYPE_LINK_OPTIONS = 6 , LOOMC_STRUCTURE_TYPE_MODULE_SERIALIZE_OPTIONS = 7 ,   LOOMC_STRUCTURE_TYPE_MODULE_DESERIALIZE_OPTIONS = 8 , LOOMC_STRUCTURE_TYPE_COMPILER_OPTIONS = 9 , LOOMC_STRUCTURE_TYPE_COMPILE_OPTIONS = 10 , LOOMC_STRUCTURE_TYPE_PASS_PROGRAM_OPTIONS = 11 ,   LOOMC_STRUCTURE_TYPE_CONTEXT_TARGET_OPTIONS = 12 , LOOMC_STRUCTURE_TYPE_TARGET_PIPELINE_OPTIONS = 13 , LOOMC_STRUCTURE_TYPE_SPIRV_EMIT_OPTIONS = 14 , LOOMC_STRUCTURE_TYPE_TARGET_SPECIALIZATION_OPTIONS = 16 ,   LOOMC_STRUCTURE_TYPE_SPIRV_PROFILE_OPTIONS = 17 , LOOMC_STRUCTURE_TYPE_EMIT_OPTIONS = 18 , LOOMC_STRUCTURE_TYPE_OPTION_DICT = 19 , LOOMC_STRUCTURE_TYPE_SPIRV_VULKANINFO_PROFILE_OPTIONS = 20 ,   LOOMC_STRUCTURE_TYPE_SOURCE_LOAD_OPTIONS = 21 , LOOMC_STRUCTURE_TYPE_SPIRV_VULKAN_FUNCTION_TABLE = 22 , LOOMC_STRUCTURE_TYPE_SPIRV_VULKAN_PROFILE_OPTIONS = 23 , LOOMC_STRUCTURE_TYPE_IREE_HAL_PROFILE_OPTIONS = 24 ,   LOOMC_STRUCTURE_TYPE_SPIRV_IREE_HAL_PROFILE_OPTIONS = 25 , LOOMC_STRUCTURE_TYPE_MODULE_FUNCTION_QUERY_OPTIONS = 26 , LOOMC_STRUCTURE_TYPE_MODULE_GLOBAL_QUERY_OPTIONS = 27 , LOOMC_STRUCTURE_TYPE_AMDGPU_PROFILE_OPTIONS = 28 ,   LOOMC_STRUCTURE_TYPE_AMDGPU_EMIT_OPTIONS = 29 , LOOMC_STRUCTURE_TYPE_ARTIFACT_MANIFEST_OPTIONS = 30 , LOOMC_STRUCTURE_TYPE_COMPILE_REPORT_OPTIONS = 31 , LOOMC_STRUCTURE_TYPE_SANITIZER_OPTIONS = 32 ,   LOOMC_STRUCTURE_TYPE_LAUNCH_CONFIG = 34 , LOOMC_STRUCTURE_TYPE_AMDGPU_IREE_HAL_PROFILE_OPTIONS = 35 }
	Structure type values used by extensible public descriptors. More...
enum	{ LOOMC_ALLOCATOR_COMMAND_MALLOC = 0 , LOOMC_ALLOCATOR_COMMAND_CALLOC = 1 , LOOMC_ALLOCATOR_COMMAND_REALLOC = 2 , LOOMC_ALLOCATOR_COMMAND_FREE = 3 }

Functions
loomc_allocator_t	loomc_allocator_system (void)
	Returns a process-global system allocator.
loomc_status_t	loomc_allocator_malloc (loomc_allocator_t allocator, loomc_host_size_t byte_length, void **out_ptr)
	Allocates zero-initialized memory from allocator.
loomc_status_t	loomc_allocator_malloc_uninitialized (loomc_allocator_t allocator, loomc_host_size_t byte_length, void **out_ptr)
	Allocates uninitialized memory from allocator.
loomc_status_t	loomc_string_view_clone (loomc_string_view_t source, loomc_allocator_t allocator, loomc_string_view_t *out_string)
	Copies a string view into allocator-owned storage.
void	loomc_allocator_free (loomc_allocator_t allocator, void *ptr)
	Frees memory previously returned by allocator.

Detailed Description

Base types, descriptors, spans, and host allocation helpers.

This header contains the small C ABI building blocks used by all other Loom C API headers. The types here avoid exposing implementation dependencies and are designed to be straightforward to mirror from foreign-function bindings.

Typedef Documentation

loomc_allocator_ctl_fn_t

typedef loomc_status_t(* loomc_allocator_ctl_fn_t) (void *self, loomc_allocator_command_t command, const void *params, void **inout_ptr)

Host allocation control callback.

Parameters

self	Callback-owned allocator state pointer.
command	Allocation command to perform.
params	Command-specific parameter structure.
inout_ptr	Pointer to allocation storage. Allocation commands write the allocated pointer. Free commands read the pointer to free.

Returns

OK on success or a non-OK status when the allocator cannot satisfy the command.

Ownership

Memory returned by an allocator must be freed through the same allocator.

loomc_host_size_t

typedef size_t loomc_host_size_t

Host allocation and container size type.

Values have the same range as C size_t. Public ABI fields use this spelling so bindings can mirror one Loom-specific type name rather than repeating the C standard library type across the API.

loomc_status_t

typedef struct iree_status_handle_t* loomc_status_t

Opaque status handle.

Small status codes are encoded directly in the pointer value. Rich status modes may allocate storage behind the handle and require loomc_status_free or loomc_status_consume_code.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
LOOMC_ALLOCATOR_COMMAND_MALLOC	Allocates memory without requiring zero initialization.
LOOMC_ALLOCATOR_COMMAND_CALLOC	Allocates memory and zeros it before returning.
LOOMC_ALLOCATOR_COMMAND_REALLOC	Resizes an existing allocation.
LOOMC_ALLOCATOR_COMMAND_FREE	Frees an existing allocation.

loomc_structure_type_t

enum loomc_structure_type_t

Structure type values used by extensible public descriptors.

Extensible descriptors store one of these values in their type field and store sizeof(descriptor_type) in structure_size. Callers zero-initialize descriptors and set the fields they use.

Enumerator
LOOMC_STRUCTURE_TYPE_NONE	No structure type was supplied.
LOOMC_STRUCTURE_TYPE_SOURCE_OPTIONS	loomc_source_options_t.
LOOMC_STRUCTURE_TYPE_WORKSPACE_OPTIONS	loomc_workspace_options_t.
LOOMC_STRUCTURE_TYPE_CONTEXT_OPTIONS	loomc_context_options_t.
LOOMC_STRUCTURE_TYPE_LINK_INDEX_BUILDER_OPTIONS	loomc_link_index_builder_options_t.
LOOMC_STRUCTURE_TYPE_LINKER_OPTIONS	loomc_linker_options_t.
LOOMC_STRUCTURE_TYPE_LINK_OPTIONS	loomc_link_options_t.
LOOMC_STRUCTURE_TYPE_MODULE_SERIALIZE_OPTIONS	loomc_module_serialize_options_t.
LOOMC_STRUCTURE_TYPE_MODULE_DESERIALIZE_OPTIONS	loomc_module_deserialize_options_t.
LOOMC_STRUCTURE_TYPE_COMPILER_OPTIONS	loomc_compiler_options_t.
LOOMC_STRUCTURE_TYPE_COMPILE_OPTIONS	loomc_compile_options_t.
LOOMC_STRUCTURE_TYPE_PASS_PROGRAM_OPTIONS	loomc_pass_program_options_t.
LOOMC_STRUCTURE_TYPE_CONTEXT_TARGET_OPTIONS	loomc_context_target_options_t.
LOOMC_STRUCTURE_TYPE_TARGET_PIPELINE_OPTIONS	loomc_target_pipeline_options_t.
LOOMC_STRUCTURE_TYPE_SPIRV_EMIT_OPTIONS	loomc_spirv_emit_options_t.
LOOMC_STRUCTURE_TYPE_TARGET_SPECIALIZATION_OPTIONS	loomc_target_specialization_options_t.
LOOMC_STRUCTURE_TYPE_SPIRV_PROFILE_OPTIONS	loomc_spirv_profile_options_t.
LOOMC_STRUCTURE_TYPE_EMIT_OPTIONS	loomc_emit_options_t.
LOOMC_STRUCTURE_TYPE_OPTION_DICT	loomc_option_dict_t.
LOOMC_STRUCTURE_TYPE_SPIRV_VULKANINFO_PROFILE_OPTIONS	loomc_spirv_vulkaninfo_profile_options_t.
LOOMC_STRUCTURE_TYPE_SOURCE_LOAD_OPTIONS	loomc_source_load_options_t.
LOOMC_STRUCTURE_TYPE_SPIRV_VULKAN_FUNCTION_TABLE	loomc_spirv_vulkan_function_table_t.
LOOMC_STRUCTURE_TYPE_SPIRV_VULKAN_PROFILE_OPTIONS	loomc_spirv_vulkan_profile_options_t.
LOOMC_STRUCTURE_TYPE_IREE_HAL_PROFILE_OPTIONS	loomc_iree_hal_profile_options_t.
LOOMC_STRUCTURE_TYPE_SPIRV_IREE_HAL_PROFILE_OPTIONS	loomc_spirv_iree_hal_profile_options_t.
LOOMC_STRUCTURE_TYPE_MODULE_FUNCTION_QUERY_OPTIONS	loomc_module_function_query_options_t.
LOOMC_STRUCTURE_TYPE_MODULE_GLOBAL_QUERY_OPTIONS	loomc_module_global_query_options_t.
LOOMC_STRUCTURE_TYPE_AMDGPU_PROFILE_OPTIONS	loomc_amdgpu_profile_options_t.
LOOMC_STRUCTURE_TYPE_AMDGPU_EMIT_OPTIONS	loomc_amdgpu_emit_options_t.
LOOMC_STRUCTURE_TYPE_ARTIFACT_MANIFEST_OPTIONS	loomc_artifact_manifest_options_t.
LOOMC_STRUCTURE_TYPE_COMPILE_REPORT_OPTIONS	loomc_compile_report_options_t.
LOOMC_STRUCTURE_TYPE_SANITIZER_OPTIONS	loomc_sanitizer_options_t.
LOOMC_STRUCTURE_TYPE_LAUNCH_CONFIG	loomc_launch_config_t.
LOOMC_STRUCTURE_TYPE_AMDGPU_IREE_HAL_PROFILE_OPTIONS	loomc_amdgpu_iree_hal_profile_options_t.

Function Documentation

loomc_allocator_free()

void loomc_allocator_free	(	loomc_allocator_t	allocator,
		void *	ptr )

Frees memory previously returned by allocator.

Parameters

allocator	Allocator that returned ptr.
ptr	Allocation to free. Passing NULL is allowed.

When ptr is non-NULL, allocator.ctl must also be non-NULL. Invalid allocator values are programmer errors because this function has no status channel.

loomc_allocator_malloc()

loomc_status_t loomc_allocator_malloc	(	loomc_allocator_t	allocator,
		loomc_host_size_t	byte_length,
		void **	out_ptr )

Allocates zero-initialized memory from allocator.

Parameters

allocator	Allocator used for the allocation.
byte_length	Number of bytes to allocate.
out_ptr	Receives the allocated memory on success.

Returns

OK on success, LOOMC_STATUS_INVALID_ARGUMENT when the allocator is invalid, or a non-OK status on allocation failure.

Ownership

The caller owns out_ptr on success and frees it with loomc_allocator_free using the same allocator.

loomc_allocator_malloc_uninitialized()

loomc_status_t loomc_allocator_malloc_uninitialized	(	loomc_allocator_t	allocator,
		loomc_host_size_t	byte_length,
		void **	out_ptr )

Allocates uninitialized memory from allocator.

Parameters

allocator	Allocator used for the allocation.
byte_length	Number of bytes to allocate.
out_ptr	Receives the allocated memory on success.

Returns

OK on success, LOOMC_STATUS_INVALID_ARGUMENT when the allocator is invalid, or a non-OK status on allocation failure.

Ownership

The caller owns out_ptr on success and frees it with loomc_allocator_free using the same allocator.

loomc_allocator_system()

loomc_allocator_t loomc_allocator_system

(

void

)

Returns a process-global system allocator.

Returns

Allocator backed by the process heap.

loomc_string_view_clone()

loomc_status_t loomc_string_view_clone	(	loomc_string_view_t	source,
		loomc_allocator_t	allocator,
		loomc_string_view_t *	out_string )

Copies a string view into allocator-owned storage.

Parameters

source	Borrowed source string view to copy.
allocator	Allocator used for the copied storage.
out_string	Receives the owned string view on success.

Returns

OK on success, LOOMC_STATUS_INVALID_ARGUMENT when the allocator or source view is invalid, or a non-OK status on allocation failure.

Empty source views produce an empty output view without allocating. The copied bytes are not NUL-terminated.

Ownership

The caller owns out_string->data on success and frees it with loomc_allocator_free using the same allocator.