#[non_exhaustive]pub enum AbiPolicy {
Strict,
Warn,
AllowUnknownEngine,
Trust,
}Expand description
How init_extension should react to
the ABI layout check.
#[non_exhaustive]: a future release may add a policy, so a match
outside quack-rs needs a wildcard arm.
use quack_rs::abi::AbiPolicy;
fn checks(policy: AbiPolicy) -> bool {
match policy {
AbiPolicy::Strict | AbiPolicy::Warn | AbiPolicy::AllowUnknownEngine => true,
AbiPolicy::Trust => false,
// error[E0004]: a wildcard arm is required
}
}Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Strict
Refuse to load unless the layout is verified compatible.
This is the default. It converts what would otherwise be silent
mis-dispatch into a clear LOAD error naming the exact remedy.
Warn
Perform the check and, on failure, print the diagnostic to stderr but continue loading.
Note the channel: this cannot use access.set_error, because DuckDB’s
loader throws whenever an extension called set_error — regardless of
what the entry point returned — which would make Warn behave exactly
like Strict. The C extension API has no non-fatal
diagnostic channel, so the message goes to stderr.
Use this when the crate is built with duckdb-1-5 but the extension
provably calls only stable-region wrappers, and you want the mismatch
visible without failing the load. Calling into the unstable region
after a failed check is undefined behaviour — Warn does not make it
safe, it only makes it loud.
AllowUnknownEngine
Refuse a layout the table says is different, but allow a DuckDB
release the table has no entry for.
This is the forward-compatibility knob. It still catches the dangerous, verifiable case — an extension built against v1.5.0 meeting v1.5.5 — while letting the extension load on a release newer than this build of quack-rs knows about.
Prefer setting QUACK_RS_TARGET_DUCKDB_VERSION instead, which turns
the same situation into a positive match rather than a suspended
judgement. Reach for this only when the build cannot set that variable.
The risk is real and asymmetric: DuckDB changed the unstable region in
every minor release from v1.3.0 on, and in the v1.5.2 patch release, so
an unknown version is more likely to differ than to match. Under this policy, an extension that calls into the
unstable region on a release it was not built for is undefined behaviour.
This is not hypothetical: before DuckDB v1.4.5 was added to the table, a
v1.5.5 build loaded into v1.4.5 under this policy and segfaulted on its
first unstable-region call. The refusal message for an unknown engine
therefore never suggests this policy.
Trust
Skip the check entirely.
Appropriate when the binary is stamped C_STRUCT_UNSTABLE, because
DuckDB then refuses to load it into any release other than the one it
was built for — making the runtime check redundant. Also appropriate when
the duckdb-1-5 feature is enabled but the extension provably calls only
stable-region wrappers.
Trait Implementations§
impl Copy for AbiPolicy
impl Eq for AbiPolicy
Source§impl From<AbiPolicy> for EntryPointOptions
impl From<AbiPolicy> for EntryPointOptions
Source§fn from(policy: AbiPolicy) -> Self
fn from(policy: AbiPolicy) -> Self
policy, with the default Registration mode.