Before you start

This guide covers writing PekoScript that talks to C. Everything here can corrupt memory if you get it wrong, and the failures are rarely local: the usual symptom is a crash somewhere unrelated, minutes later.

Read the collector pages before writing any C that touches a managed value. The rules are short, and following them is not optional.

What this covers

• Declaring a C surface in a .peko.h header.
• The garbage collector boundary: what moves, what is traced, and what is not.
• Threads, parking, and why a missing bracket deadlocks the process.
• Adding C to a package and linking a vendored library.
• Writing per-platform code on both sides.
• The low-level PekoScript features: raw scalars, casts, pointers.

The one-paragraph summary

The collector is stop-the-world and it moves objects. A raw pointer into the managed heap is valid only until the next collection. C functions are assumed not to collect, which is why passing a managed buffer into a synchronous C call is safe; the moment a call can allocate or block, that assumption breaks and you need a handle or a parked thread. Anything reached only through opaque, cstr, or a reference is invisible to the collector and will be reclaimed.