clips-bindings 0.1.2+clips-6.4.2

Safe, idiomatic, custom-written Rust bindings for the CLIPS 6.4.2 embedding API
Documentation
//! Layout verification for the custom-written ABI declarations in [`crate::ffi`].
//!
//! CLIPS exposes a small number of non-opaque structures whose layouts this
//! crate reproduces by hand. Getting one of them wrong is not a subtle bug: it
//! misreads or corrupts memory the C code owns.
//!
//! The check is a comparison against C, not against constants. `shim/abi_layout.c`
//! is compiled with the same target, dialect, and flags as the CLIPS sources and
//! exports one `sizeof`/`offsetof` per field; the tests below assert that Rust's
//! own [`size_of`], [`align_of`], and [`offset_of!`] agree with it. Because
//! neither side is transcribed from a header by hand, they cannot drift together
//! in the same wrong direction — which is exactly the failure a table of
//! hand-copied constants would miss.
//!
//! This is the crate's only C file, and layout verification is the only thing it
//! does. It computes nothing at runtime and CLIPS never calls it.

/// Mirror of `struct clipsAbiLayout` in `shim/abi_layout.c`.
///
/// Every field is a `usize`, so the mirror's own layout is trivial and the
/// `magic`/`self_size`/`sentinel` guards confirm the two agree on length before
/// any field is trusted.
#[cfg(test)]
#[repr(C)]
#[derive(Debug)]
pub(crate) struct ClipsAbiLayout {
    magic: usize,
    self_size: usize,

    size_of_long: usize,
    size_of_pointer: usize,
    size_of_size_t: usize,

    type_header_size: usize,
    type_header_align: usize,
    type_header_type: usize,

    clips_value_size: usize,
    clips_value_align: usize,

    lexeme_size: usize,
    lexeme_align: usize,
    lexeme_header: usize,
    lexeme_next: usize,
    lexeme_count: usize,
    lexeme_contents: usize,

    float_size: usize,
    float_align: usize,
    float_header: usize,
    float_next: usize,
    float_count: usize,
    float_contents: usize,

    integer_size: usize,
    integer_align: usize,
    integer_header: usize,
    integer_next: usize,
    integer_count: usize,
    integer_contents: usize,

    multifield_size: usize,
    multifield_align: usize,
    multifield_header: usize,
    multifield_busy_count: usize,
    multifield_length: usize,
    multifield_next: usize,
    multifield_contents: usize,

    udf_value_size: usize,
    udf_value_align: usize,
    udf_value_supplemental_info: usize,
    udf_value_value: usize,
    udf_value_begin: usize,
    udf_value_range: usize,
    udf_value_next: usize,

    udf_context_size: usize,
    udf_context_align: usize,
    udf_context_environment: usize,
    udf_context_context: usize,
    udf_context_the_function: usize,
    udf_context_last_position: usize,
    udf_context_last_arg: usize,
    udf_context_return_value: usize,

    string_builder_size: usize,
    string_builder_align: usize,
    string_builder_environment: usize,
    string_builder_contents: usize,
    string_builder_buffer_reset: usize,
    string_builder_length: usize,
    string_builder_buffer_maximum: usize,

    sentinel: usize,
}

#[cfg(test)]
unsafe extern "C" {
    /// Filled in at compile time by the C compiler that built CLIPS.
    #[link_name = "ClipsAbiLayoutTable"]
    pub(crate) static CLIPS_ABI_LAYOUT: ClipsAbiLayout;
}

#[cfg(test)]
mod tests {
    use std::ffi::{c_long, c_void};
    use std::mem::{align_of, offset_of, size_of};

    use super::{CLIPS_ABI_LAYOUT, ClipsAbiLayout};
    use crate::ffi;

    /// Matches `CLIPS_ABI_MAGIC` in the shim.
    const MAGIC: usize = 0x4341_4249;

    fn layout() -> &'static ClipsAbiLayout {
        // Immutable data initialised before `main`, so reading it is sound and
        // needs no synchronisation.
        unsafe { &CLIPS_ABI_LAYOUT }
    }

    /// Nothing below means anything unless the table really is the shim's, and
    /// unless both sides agree on how long it is.
    #[test]
    fn the_layout_table_is_populated_and_the_same_length_on_both_sides() {
        let c = layout();
        assert_eq!(c.magic, MAGIC, "ABI layout table is missing or mislinked");
        assert_eq!(c.sentinel, MAGIC, "ABI layout table is truncated");
        assert_eq!(
            c.self_size,
            size_of::<ClipsAbiLayout>(),
            "the Rust mirror of struct clipsAbiLayout has a different field count"
        );
    }

    /// The scalar widths every other expectation is built on.
    #[test]
    fn rust_and_c_agree_on_the_primitive_widths() {
        let c = layout();
        assert_eq!(size_of::<c_long>(), c.size_of_long);
        assert_eq!(size_of::<*const c_void>(), c.size_of_pointer);
        assert_eq!(size_of::<usize>(), c.size_of_size_t);
    }

    #[test]
    fn type_header_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::TypeHeader>(), c.type_header_size);
        assert_eq!(align_of::<ffi::TypeHeader>(), c.type_header_align);
        assert_eq!(offset_of!(ffi::TypeHeader, type_), c.type_header_type);
    }

    #[test]
    fn clips_value_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::CLIPSValue>(), c.clips_value_size);
        assert_eq!(align_of::<ffi::CLIPSValue>(), c.clips_value_align);
    }

    /// The bitfield word between `count` and `contents` has no address, so C
    /// cannot report its offset. It is pinned indirectly: the Rust mirror puts a
    /// `u32` there, and any disagreement about its width or position moves
    /// `contents`, which is checked.
    #[test]
    fn atom_prefixes_match_the_c_layout() {
        let c = layout();

        assert_eq!(size_of::<ffi::CLIPSLexeme>(), c.lexeme_size);
        assert_eq!(align_of::<ffi::CLIPSLexeme>(), c.lexeme_align);
        assert_eq!(offset_of!(ffi::CLIPSLexeme, header), c.lexeme_header);
        assert_eq!(offset_of!(ffi::CLIPSLexeme, next), c.lexeme_next);
        assert_eq!(offset_of!(ffi::CLIPSLexeme, count), c.lexeme_count);
        assert_eq!(offset_of!(ffi::CLIPSLexeme, contents), c.lexeme_contents);

        assert_eq!(size_of::<ffi::CLIPSFloat>(), c.float_size);
        assert_eq!(align_of::<ffi::CLIPSFloat>(), c.float_align);
        assert_eq!(offset_of!(ffi::CLIPSFloat, header), c.float_header);
        assert_eq!(offset_of!(ffi::CLIPSFloat, next), c.float_next);
        assert_eq!(offset_of!(ffi::CLIPSFloat, count), c.float_count);
        assert_eq!(offset_of!(ffi::CLIPSFloat, contents), c.float_contents);

        assert_eq!(size_of::<ffi::CLIPSInteger>(), c.integer_size);
        assert_eq!(align_of::<ffi::CLIPSInteger>(), c.integer_align);
        assert_eq!(offset_of!(ffi::CLIPSInteger, header), c.integer_header);
        assert_eq!(offset_of!(ffi::CLIPSInteger, next), c.integer_next);
        assert_eq!(offset_of!(ffi::CLIPSInteger, count), c.integer_count);
        assert_eq!(offset_of!(ffi::CLIPSInteger, contents), c.integer_contents);
    }

    #[test]
    fn multifield_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::Multifield>(), c.multifield_size);
        assert_eq!(align_of::<ffi::Multifield>(), c.multifield_align);
        assert_eq!(offset_of!(ffi::Multifield, header), c.multifield_header);
        assert_eq!(
            offset_of!(ffi::Multifield, busy_count),
            c.multifield_busy_count
        );
        assert_eq!(offset_of!(ffi::Multifield, length), c.multifield_length);
        assert_eq!(offset_of!(ffi::Multifield, next), c.multifield_next);
        assert_eq!(offset_of!(ffi::Multifield, contents), c.multifield_contents);
    }

    #[test]
    fn udf_value_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::UDFValue>(), c.udf_value_size);
        assert_eq!(align_of::<ffi::UDFValue>(), c.udf_value_align);
        assert_eq!(
            offset_of!(ffi::UDFValue, supplemental_info),
            c.udf_value_supplemental_info
        );
        assert_eq!(offset_of!(ffi::UDFValue, value), c.udf_value_value);
        assert_eq!(offset_of!(ffi::UDFValue, begin), c.udf_value_begin);
        assert_eq!(offset_of!(ffi::UDFValue, range), c.udf_value_range);
        assert_eq!(offset_of!(ffi::UDFValue, next), c.udf_value_next);
    }

    #[test]
    fn udf_context_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::UDFContext>(), c.udf_context_size);
        assert_eq!(align_of::<ffi::UDFContext>(), c.udf_context_align);
        assert_eq!(
            offset_of!(ffi::UDFContext, environment),
            c.udf_context_environment
        );
        assert_eq!(offset_of!(ffi::UDFContext, context), c.udf_context_context);
        assert_eq!(
            offset_of!(ffi::UDFContext, the_function),
            c.udf_context_the_function
        );
        assert_eq!(
            offset_of!(ffi::UDFContext, last_position),
            c.udf_context_last_position
        );
        assert_eq!(
            offset_of!(ffi::UDFContext, last_arg),
            c.udf_context_last_arg
        );
        assert_eq!(
            offset_of!(ffi::UDFContext, return_value),
            c.udf_context_return_value
        );
    }

    #[test]
    fn string_builder_matches_the_c_layout() {
        let c = layout();
        assert_eq!(size_of::<ffi::StringBuilder>(), c.string_builder_size);
        assert_eq!(align_of::<ffi::StringBuilder>(), c.string_builder_align);
        assert_eq!(
            offset_of!(ffi::StringBuilder, environment),
            c.string_builder_environment
        );
        assert_eq!(
            offset_of!(ffi::StringBuilder, contents),
            c.string_builder_contents
        );
        assert_eq!(
            offset_of!(ffi::StringBuilder, buffer_reset),
            c.string_builder_buffer_reset
        );
        assert_eq!(
            offset_of!(ffi::StringBuilder, length),
            c.string_builder_length
        );
        assert_eq!(
            offset_of!(ffi::StringBuilder, buffer_maximum),
            c.string_builder_buffer_maximum
        );
    }
}