C Advanced API

Session configuration

Select an advanced backend or context and require explicit solver capabilities.

A stable session prepares one selected policy and can solve successive request snapshots. Use these advanced setters only when the application must select an extension backend or require specific execution capabilities. Configuration is completed before maelys_datalog_session_create_configured().

Types

Used from other pages

These types are defined on the linked pages; this page uses them in the roles below.

Type	Use on this page	Defined in
`maelys_datalog_session_config_t`	Input configuration handle shared with stable setters.	Stable Solving

Extension types

These descriptors come from the extension headers named below.

Type	Definition
`maelys_datalog_backend_t`	ABI 5 extension backend descriptor from `<maelys/datalog_backend.h>`.
`maelys_datalog_backend_storage_t`	Caller-owned backend workspace descriptor from the same header.
`maelys_datalog_context_t`	Sealed extension catalog from `<maelys/datalog_extension.h>`.

Functions

Function	Purpose
`maelys_datalog_session_config_set_backend()`	Select a copied direct backend descriptor.
`maelys_datalog_session_config_set_context()`	Select a backend by name from a sealed context.
`maelys_datalog_session_config_set_requirements()`	Require capabilities and a work budget.
`maelys_datalog_backend_storage_requirements()`	Measure backend preparation storage before session creation.
`maelys_datalog_session_config_set_backend_storage()`	Attach the caller-owned buffer to the configuration.

Choose one backend route

The two backend setters replace each other; the last successful selection controls session creation. A direct backend descriptor is copied into the config, but its callback code must stay loaded while sessions use it. A context selection retains that sealed context. The policy must have been compiled in the same context. Passing NULL as backend_name selects its reference backend; a non-NULL name is an exact selection, not a fallback hint.

maelys_datalog_status_t
maelys_datalog_session_config_set_backend(
maelys_datalog_session_config_t *config,
const maelys_datalog_backend_t *backend
);

Selects the backend descriptor that a future configured session will use. It changes the configuration, not an already-created session.

Arguments

configmaelys_datalog_session_config_t *

Configuration to update before creating a session.

backendconst maelys_datalog_backend_t *

Versioned descriptor copied into the config; NULL or the built-in reference descriptor selects the reference backend.

Name	Type	Meaning
config	maelys_datalog_session_config_t *	Configuration to update before creating a session.
backend	const maelys_datalog_backend_t *	Versioned descriptor copied into the config; NULL or the built-in reference descriptor selects the reference backend.

Return value

maelys_datalog_status_t

OK when the descriptor is accepted; invalid ABI or descriptor fields are rejected.

maelys_datalog_status_t
maelys_datalog_session_config_set_context(
maelys_datalog_session_config_t *config,
maelys_datalog_context_t *context,
const char *backend_name
);

Selects a backend from a sealed extension context for a future configured session. The policy must have been compiled in that same context.

Arguments

configmaelys_datalog_session_config_t *

Configuration to update.

contextmaelys_datalog_context_t *

Already sealed catalog used to compile the selected policy.

backend_nameconst char *

Registered backend name, or NULL for the reference backend in this context.

Name	Type	Meaning
config	maelys_datalog_session_config_t *	Configuration to update.
context	maelys_datalog_context_t *	Already sealed catalog used to compile the selected policy.
backend_name	const char *	Registered backend name, or NULL for the reference backend in this context.

Return value

maelys_datalog_status_t

OK on selection; INVALID_STATE for an unsealed context or NOT_FOUND for an unknown backend name.

Backend preparation storage

A backend may need memory to prepare a policy once and reuse that preparation for many requests. This is not the explanation workspace: that separate buffer holds a Why-true or Why-false document after solving.

Ask for the backend's requirements, provide a suitably aligned buffer, set its descriptor on the configuration, then create the session. The host copies the descriptor but borrows the buffer; keep it immovable until the session is destroyed. Each live session needs separate storage, including the pair borrowed by an event window.

maelys_datalog_status_t
maelys_datalog_backend_storage_requirements(
const maelys_datalog_policy_t *policy,
size_t policy_index,
const maelys_datalog_backend_t *backend,
size_t *out_bytes,
size_t *out_alignment
);

Reports the selected backend's preparation requirements for one loaded policy without allocating or preparing a session.

Arguments

policyconst maelys_datalog_policy_t *

Live loaded policy set.

policy_indexsize_t

Zero-based policy index within that set.

backendconst maelys_datalog_backend_t *

Selected backend descriptor, or NULL for the reference backend.

out_bytessize_t *

Receives the required byte capacity on success; zero is valid.

out_alignmentsize_t *

Receives the required nonzero power-of-two alignment, no greater than alignof(max_align_t).

Name	Type	Meaning
policy	const maelys_datalog_policy_t *	Live loaded policy set.
policy_index	size_t	Zero-based policy index within that set.
backend	const maelys_datalog_backend_t *	Selected backend descriptor, or NULL for the reference backend.
out_bytes	size_t *	Receives the required byte capacity on success; zero is valid.
out_alignment	size_t *	Receives the required nonzero power-of-two alignment, no greater than alignof(max_align_t).

Return value

maelys_datalog_status_t

OK with both outputs filled; invalid inputs, policy selection or backend requirements return an error and leave both outputs unchanged.

maelys_datalog_status_t
maelys_datalog_session_config_set_backend_storage(
maelys_datalog_session_config_t *config,
const maelys_datalog_backend_storage_t *storage
);

Copies a backend-storage descriptor into a session configuration without copying or owning its buffer.

Arguments

configmaelys_datalog_session_config_t *

Configuration to update before creating the session.

storageconst maelys_datalog_backend_storage_t *

Descriptor of the caller-owned buffer; NULL clears this selection.

Name	Type	Meaning
config	maelys_datalog_session_config_t *	Configuration to update before creating the session.
storage	const maelys_datalog_backend_storage_t *	Descriptor of the caller-owned buffer; NULL clears this selection.

Return value

maelys_datalog_status_t

OK when the descriptor is accepted; malformed descriptors are rejected. Session creation checks the size and alignment against the selected backend and returns INVALID_ARGUMENT before prepare if they are insufficient.

The descriptor, declared in <maelys/datalog_backend.h>, has four fields:

Field	Type	Meaning
`struct_size`	`size_t`	Set to `sizeof(maelys_datalog_backend_storage_t)`.
`bytes`	`void *`	The caller's aligned buffer; NULL is allowed only with zero size and zero requirements.
`size`	`size_t`	Available bytes.
`alignment`	`size_t`	Guaranteed nonzero power-of-two alignment, at most `alignof(max_align_t)`.

Changing backend or context selection does not clear this storage. Requirements are checked again at session creation. There is no implicit allocation or fallback to satisfy missing backend storage; supplying it does not promise that the entire session constructor allocates nothing.

Backend ABI 5: candidate, then acceptance

Extension authors must rebuild ABI 4 backends. ABI 5 adds storage_requirements, passes the validated descriptor to prepare(program, storage, out_state), and requires an infallible commit. A successful backend solve first produces a candidate. The host validates and installs it before commit; window adapters wait until publication is irrevocable. An abandoned candidate is destroyed without commit. The backend must preserve its previously committed state until that point.

See the installed callback contract and the backend transaction tests. Consumer API 2, program ABI 2 and diagnostic ABI 1 do not change with this backend migration.

Require what the session must support

capabilities is a mask from the public capability constants. work_limit is a requested ceiling; 0 means no additional work-budget requirement. Unsupported combinations fail explicitly when the configured session is created rather than silently switching to another backend.

maelys_datalog_status_t
maelys_datalog_session_config_set_requirements(
maelys_datalog_session_config_t *config,
uint64_t capabilities,
uint64_t work_limit
);

Records the capabilities and optional work ceiling required of a future session. Whether the selected backend can meet them is checked when the session is created.

Arguments

configmaelys_datalog_session_config_t *

Existing configuration handle.

capabilitiesuint64_t

Required capability mask; unknown bits are rejected.

work_limituint64_t

Requested work ceiling; zero means no extra requirement.

Name	Type	Meaning
config	maelys_datalog_session_config_t *	Existing configuration handle.
capabilities	uint64_t	Required capability mask; unknown bits are rejected.
work_limit	uint64_t	Requested work ceiling; zero means no extra requirement.

Return value

maelys_datalog_status_t

OK when the mask is well formed; whether the selected backend can meet it is checked at session creation.

CODE

static maelys_datalog_status_t prepare_config(
    maelys_datalog_session_config_t **out_config) {
    maelys_datalog_status_t rc = maelys_datalog_session_config_create(out_config);
    if (rc != MAELYS_DATALOG_STATUS_OK) return rc;
    rc = maelys_datalog_session_config_set_requirements(
        *out_config, MAELYS_DATALOG_CAP_NEGATION, 0u);
    if (rc != MAELYS_DATALOG_STATUS_OK) {
        maelys_datalog_session_config_free(*out_config);
        *out_config = NULL;
    }
    return rc;
}

The stable explanation-workspace setting composes with these requirements; selecting an advanced backend does not erase it. A custom backend may return UNSUPPORTED for reference-only structured explanations or filter statistics. The engine does not fall back silently to the reference backend.