// Obj-C blocks bridged to sx closures.
//
// Apple's block ABI (clang's "Block Implementation Specification"): a block
// pointer is a struct whose first five fields are { isa, flags, reserved,
// invoke, descriptor } followed by per-block captured state. When an API
// like `[UIView animateWithDuration:animations:]` receives a block, the
// runtime reads `invoke` and calls it with the block pointer as the first
// argument. UIKit / Foundation callers always `_Block_copy` synchronously
// before returning, so a stack-allocated block is safe to pass directly.
//
// We layer the sx closure onto Apple's layout by appending two pointer
// fields to the standard 32-byte header: `sx_env` (the closure's captured
// environment pointer) and `sx_fn` (the closure trampoline). The per-
// signature `__block_invoke_*` C-ABI fn knows the offsets and calls
// through to `sx_fn(sx_env, args...)`.
//
// ── Lifetime contract ───────────────────────────────────────────────────
// `xx <closure> : *Block` returns a pointer into the surrounding sx
// function's stack frame. Same rule as `&local_var`: pass it directly to
// a callee that consumes it immediately or `_Block_copy`s internally
// (UIKit/Foundation always do). Don't store the pointer to use after the
// caller returns. If you need that, ship a `Block_copy`-backed sibling
// API and use it instead.

// Standard 32-byte block header plus two trailing slots for the sx closure
// it wraps. Total = 48 bytes.
Block :: struct {
    isa: *void;
    flags: s32;
    reserved: s32;
    invoke: *void;
    descriptor: *void;
    sx_env: *void;
    sx_fn: *void;
}

// Per-block-shape metadata. The runtime reads `size` when copying the
// block to the heap, so it must equal the actual instance size.
BlockDescriptor :: struct {
    reserved: u64;
    size: u64;
}

// libSystem isa pointer for stack-allocated blocks. Resolved at link time
// (auto-linked on every Apple target via libSystem).
_NSConcreteStackBlock : *void #foreign;

// Shared descriptor for the 48-byte sx-block layout. All Into impls below
// point their `descriptor` field at this.
__sx_block_descriptor : BlockDescriptor = .{
    reserved = 0,
    size = 48,
};

// M5.A — `xx closure : Block` casts are handled by the compiler.
// For every closure signature seen at a cast site, the compiler
// synthesises:
//   1. A C-ABI trampoline `__block_invoke_<sig>` matching Apple's
//      `__block_literal.invoke` calling convention.
//   2. Inline Block-struct construction at the cast site, with
//      `invoke` pointing at the synthesised trampoline and
//      `sx_env`/`sx_fn` taken from the closure value.
//
// User-facing surface: `xx my_closure : Block` for ANY closure
// signature. No per-signature stdlib boilerplate. The shared
// infrastructure above (`Block`, `BlockDescriptor`,
// `_NSConcreteStackBlock`, `__sx_block_descriptor`) is referenced
// by the synthesised code; users only need to `#import` this module.