Callback registration

Platform spec article

Callback registration

Back to Export and callbacks ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-hub-authority Feature hub owns normative contract Accepted

   Beskid-to-foreign export authority.

   Context

   Export/callback rules were scattered between runtime and language-meta drafts.

   Decision

   This feature hub must own normative MUST/SHOULD for Beskid export and callback registration (user interop).

   Consequences

   Distinct from runtime builtin exports on Rust ABI profile.

   Verification anchors

   /platform-spec/language-meta/interop/export-and-callbacks/

   Open full ADR page

2. 0002-distinct-from-runtime-builtins User export distinct from runtime builtins Accepted

   Export symbols are generated; builtins stay beskid_abi.

   Context

   Plugin authors confused generated exports with frozen JIT builtin tables.

   Decision

   User export symbols are generated from Beskid compilation units. Frozen runtime builtin exports remain on beskid_abi / Rust ABI profile — export-only work must not change BESKID_RUNTIME_ABI_VERSION.

   Consequences

   Codegen plans export metadata beside ExternImport; trampolines use runtime TLS hooks.

   Verification anchors

   /platform-spec/language-meta/interop/export-and-callbacks/ implementation anchors.

   Open full ADR page

3. 0003-export-pub-functions-v03 Export on pub functions v0.3 Accepted

   Contract vtables as Standard export remain out of scope.

   Context

   Embedding hosts need a minimal stable export surface before full vtable stories.

   Decision

   v0.3 Standard must support [Export] on pub functions with FFI-permitted types. Exporting arbitrary contract vtables as Standard is out of scope for v0.3.

   Consequences

   Callback registration table protocol is Standard; foreign-thread entry without host contract is Proposed v0.3.2+.

   Verification anchors

   export attribute; callback registration.

   Open full ADR page

4. 0004-spec-standard-impl-may-trail Standard spec implementation may trail Accepted

   Normative text can lead reference compiler export support.

   Context

   v0.3 is spec-first for interop; codegen for export is still landing.

   Decision

   This feature is Standard in v0.3 specification. Reference compiler support may trail; verification article records gaps until codegen lands.

   Consequences

   Contributors implement against ADRs without downgrading spec status to Proposed.

   Verification anchors

   verification and traceability.

   Open full ADR page

Articles

• Callback registration Host registration table protocol for Beskid exports invoked from foreign code (v0.3). article Standard Reviewed Sat May 23
• Export attribute Normative Export metadata for pub functions exposed to foreign hosts (v0.3). article Standard Reviewed Wed May 20
• Export and callbacks — Verification and traceability Conformance fixtures for Export and callback registration (v0.3). article Standard Reviewed Sat May 23

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  Export and callbacks

  Parent feature hub

• Feature
  Callback call shapes

  Abstract shapes

Model

Foreign hosts (game engines, shells, OS services) register Beskid callbacks before or during runtime. v0.3 Standard defines:

1. Exported Beskid functions — normal [Export] entrypoints.
2. Registration contract — a Beskid contract describing callback function-pointer types the host implements or consumes.
3. Registration export — a stable C symbol the host calls to install a table of function pointers.

Registration export (normative shape)

The platform reserves a runtime or generated symbol (exact name is toolchain-defined; example):

beskid_register_callbacks(version: u32, table: *const CallbackTable, count: usize) -> i32

Field	Meaning
version	User FFI layout band — must match BESKID_USER_FFI_LAYOUT_BAND
table	Array of { symbol_id, fn_ptr, userdata } rows
count	Number of rows
Return	0 success; non-zero stable error codes

Hosts must reject unknown version values.

Reference symbol

The reference runtime exposes beskid_register_callbacks from compiler/crates/beskid_runtime/src/builtins/callback.rs, registered in RUNTIME_EXPORT_SYMBOLS and BUILTIN_SPECS via compiler/crates/beskid_abi/src/symbols.rs. Hosts must pass version == BESKID_USER_FFI_LAYOUT_BAND (initial Standard value 1).

Beskid-side callback exports

Each callback slot points at a [Export(Abi:"C")] function or a compiler-generated trampoline that:

• Enters runtime TLS / heap scope.
• Performs any GC safepoint policy required before executing Beskid code.
• Maps parameters from C layout to Beskid types.

Import-side function pointers

Extern contracts may accept function-pointer parameters when the pointee is a documented Export or trampoline symbol. See callback call shapes.

Non-goals (v0.3)

• Automatic binding generation from C headers.
• Foreign-thread callback without host lifecycle contract (Proposed later).