FFI Boundary Semantics

This article is about what actually crosses the R/C boundary in Rtinycc:

when values are copied
when they are borrowed
when they stay as raw addresses
when wrappers allocate temporary storage

The statements below are based on the implemented wrapper generator and runtime helpers.

Scalar Inputs Are Converted

Scalar inputs are converted at the boundary. For example:

i8, i16, i32, u8, u16 use integer coercion plus range checks
i64, u32, u64 use numeric coercion plus integer-value checks
bool rejects NA
f32 and f64 are read from R numerics

So scalar arguments are not zero-copy views into R objects. They become C scalars inside the wrapper.

Vector Inputs Are Usually Borrowed

The array input types:

raw
integer_array
numeric_array
logical_array

are passed as direct pointers into the underlying R vector storage.

That means:

no extra buffer is allocated by the wrapper
C sees the existing vector data
mutation from C writes into the same memory region

This is the main zero-copy part of the FFI boundary.

`cstring_array` Is Rebuilt Per Call

cstring_array is different. The wrapper allocates a temporary const char ** with R_alloc() and fills it by translating each R string element.

So:

the pointer array itself is allocated for the call
each element points at translated string data
this is not the same as passing a pre-existing C array through unchanged

Returned Arrays Are Copied into Fresh R Vectors

Array returns are always copied into a newly allocated R vector. The wrapper uses the declared length_arg to size the R result, then memcpy() copies the returned C buffer into that vector.

If free = TRUE, the wrapper also frees the original returned buffer after the copy.

So array returns are not borrowed views into C memory.

Returned `cstring` Values Are Copied

For cstring returns, the wrapper creates an R string with mkString() when the returned pointer is non-NULL.

That means the resulting R value is a copy in R-managed memory, not a retained external pointer to the original C string.

Returned `ptr` Values Stay as Pointers

For ptr returns, the wrapper constructs an external pointer around the raw address.

That means:

no pointee copy is made
ownership is not implied
the pointer may dangle if the underlying C storage goes away

The same distinction matters for globals and struct fields.

`sexp` Passes Through Directly

sexp is the most direct boundary mode:

input sexp arguments are passed through as SEXP
returned sexp values are returned directly

This is useful when you want the R C API contract rather than the stricter FFI conversion layer.

Owned vs Borrowed Helper Pointers

At the helper level:

tcc_malloc() and tcc_cstring() create owned external pointers
tcc_data_ptr() and tcc_read_ptr() return borrowed external pointers
struct field address helpers and many raw pointer returns are borrowed views
named nested struct getters such as struct_outer_get_child() return borrowed nested views into the owning struct storage

Use tcc_ptr_is_owned() when you need to distinguish these cases in R code.

Bitfields Are Scalar Helpers, Not Addressable Views

Bitfield helpers behave like scalar getter/setter helpers at the R boundary, but that does not make them ordinary addressable fields.

In particular:

bitfield getters return copied scalar values
bitfield setters write scalar values back through the compiler-managed bitfield storage
tcc_field_addr() and tcc_container_of() reject bitfield members

So bitfields are intentionally excluded from the borrowed-address helper model.

Serialization Boundary

Compiled tcc_compiled objects store enough recipe information to recompile after serialize() / unserialize() or readRDS().

Raw pointers and raw tcc_state objects do not gain that behavior. After serialization they are just dead addresses or invalid states, not auto-reconstructed resources. The same applies to callback tokens, struct/union external pointers, and helper allocations from tcc_malloc() or tcc_cstring(): they do not serialize as live native resources.