Home /Modules/comparison/ABI-AND-INTEROPERABILITY.md

ABI-AND-INTEROPERABILITY.md

comparison/ABI-AND-INTEROPERABILITY.md · 55 line(s) · markdown

ABI and Interoperability Standards

Standard SCS-ABI-001 | Edition 1.0

1. Boundary hierarchy

Preferred order: (1) versioned language-neutral serialized data/protocol; (2) stable C ABI with opaque handles and fixed-width values; (3) documented Java/JNI interface when a JVM integration actually exists; (4) C++ ABI pinned to compiler, standard library, and runtime; (5) private implementation details.

2. SLeeLa to C

The C ABI is the preferred native cross-compiler boundary. Public functions should use C-compatible declarations, explicit calling convention/export macros, fixed-width integers, opaque handles, and versioned structures.

Illustrative pattern only; these are not claims of existing exported symbols:

typedef struct SLContext SLContext; typedef struct { uint32_t struct_size; uint32_t abi_major; uint32_t abi_minor; int32_t status; } SLResult;

int32_t sl_context_create(SLContext **out_context); int32_t sl_context_run(SLContext *context, SLResult *out_result); void sl_context_destroy(SLContext *context);

Define structure size/version, reserved fields, nullability, ranges, ownership, release functions, thread-safety, reentrancy, errors, and diagnostic retrieval. Never expose compiler-private C++ objects through a stable C header.

3. C++ implementation

C++ may implement the engine, object model, orchestration, and wrappers. Keep exceptions, RTTI, templates, STL layout, and compiler-specific class layout behind the C ABI unless a particular C++ ABI is explicitly pinned. Use RAII internally and translate exceptions to stable status codes at exported C functions.

4. Java modes

ModeDescription
External processSLeeLa launches Java executable; arguments/streams/files cross process boundary
JNINative code calls into/from a JVM through JNI
Embedded JVMSLeeLa process creates/manages a JVM through Invocation API
Serialized serviceJava and SLeeLa communicate using a defined protocol

The documented default SLeeLa Java path is external process delegation. Do not label it JNI or embedded JVM. Embedded execution requires lifecycle, thread attachment, shutdown, class-loader, exception, and platform qualification.

For process mode, pass arguments separately, avoid shell-string construction, capture exit status, and define stdin/stdout/stderr. Do not promise shared Java object identity or heap access.

5. Java conversions

Define primitive conversions, string encoding, array copying/pinning/lifetime, object references as opaque handles, and exception-to-status translation. JNI local/global reference and thread-attachment rules apply only when JNI is implemented.

6. Platform ABI

Record architecture, OS, object format, compiler, calling convention, data model, alignment, and runtime libraries. Windows x64 and System V x86-64 do not share identical calling conventions. Do not assume long width or structure packing is universal.

7. Versioning

Version language syntax, compiler, VM artifact format, VM ABI, native library ABI, and Java/JDK compatibility independently. Major ABI changes require explicit compatibility decisions. Minor additions must preserve layouts or use size/version negotiation.

8. Security

Validate lengths, indexes, tags, handles, and versions. Treat foreign inputs as untrusted. Enforce resolver/capability policy before execution. Bound memory, CPU, recursion, and message sizes. Do not interpolate untrusted input into shell commands or expose uninitialized memory.

9. Required tests

Test ABI mismatch, structure-size mismatch, null pointers, invalid handles, integer boundaries, string encoding, array lengths, ownership transfer, double release, errors/exceptions, process exit codes, argument boundaries, concurrency, and shutdown on each claimed platform.