% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/callbacks.R
\name{tcc_callback}
\alias{tcc_callback}
\title{Register an R function as a callback}
\usage{
tcc_callback(fun, signature, threadsafe = FALSE)
}
\arguments{
\item{fun}{An R function to be called from C}

\item{signature}{C function signature string (e.g., "double (*)(int, double)")}

\item{threadsafe}{Whether to enable thread-safe invocation (experimental)}
}
\value{
A tcc_callback object (externalptr wrapper)
}
\description{
Wraps an R function so it can be passed as a C function pointer
to compiled code. The callback will be invoked via a trampoline
that marshals arguments between C and R.
}
\details{
Thread safety: callbacks are executed on the R main thread only. Invoking
a callback from a worker thread is unsupported and may crash R. The
\code{threadsafe} flag is currently informational only.

If a callback raises an error, a warning is emitted and a type-appropriate
default value is returned.

When binding callbacks with \code{tcc_bind()}, use a \verb{callback:<signature>}
argument type so a synchronous trampoline is generated. The trampoline
expects a \verb{void*} user-data pointer as its first argument; pass
\code{tcc_callback_ptr(cb)} as the user-data argument to the C API. For
thread-safe usage from worker threads, use \verb{callback_async:<signature>}
which schedules the call on the main thread and returns a default value.

Pointer arguments (e.g., \code{double*}, \code{int*}) are passed as
external pointers. Lengths must be supplied separately if needed.

The return type may be any scalar type supported by the FFI mappings
(e.g., \code{i32}, \code{f64}, \code{bool}, \code{cstring}), or
\code{SEXP} to return an R object directly.

Callback lifetime: callbacks are eventually released by finalizers and
package unload. Call \code{tcc_callback_close()} when you want deterministic
invalidation and earlier release of the preserved R function.
}
