Wrapping a C library
A C library is shaped by C. It has return codes, pointers that C fills, handles with a free function and variadic functions. A good wrapper hides all of that. The extern block is the raw layer. The public functions on top of it look like the rest of Agentica. SQLite is a whole library done this way. This page gives the rules. The examples name the Linux libraries (libc.so.6, libm.so.6).
Two layers #
The raw layer is one extern block per library. Copy each signature from the C header and keep the C names. A name has no ? or ! (PARSE-EXTERN-NAME). The raw layer is not part of your API. The public layer is plain Agentica. A String with a NUL character stops the program when it crosses to C (RUNTIME-INVALID-CHARACTER), so a wrapper that must not stop checks its String inputs first; the examples skip that check.
| In C | In the public API |
|---|---|
| A return code or a NULL | Result[T], with an error text that names the bad value |
| A handle and the function that frees it | a resource, returned in a Result |
An int that answers yes or no | a function named name? that returns Bool |
| A pointer that C fills | an out parameter, turned into the fields of your own struct |
| Memory that the caller gives and C fills | a String or a List copied out of a Native.memory_pointer block (see Buffers and block forms below) |
| A call that may take long | a compute def in the raw layer, so the other tasks keep running; the wrapper calls it like any function |
| A variadic function | functions of a normal shape (see Variadic functions below) |
| A struct of options passed by value, with a function that gives the defaults | a struct of your own with the options the caller may set, copied into the C struct by the wrapper (see Structs of options below) |
A table of function pointers (api->CreateEnv(...)) | C.Function calls in the raw layer, with the slots as constants of the wrapper (see Tables of function pointers below) |
A block with a resource or a struct sits with the types of the file, at the top and before every function, and its defs do not count as functions in the declaration order (CHECK-DECL-ORDER). So the wrapper can sit in the same file as the block. The block is public like any declaration, so callers can name the type, and the raw defs are importable too. A block with neither has no such rule. Its defs count as functions, so it stays at the end of the file, after private when the raw defs are not part of the API, as in the examples after this one.
extern "libc.so.6"
resource Stream, free: fclose
def fopen(path: C.String, mode: C.String) -> Stream
def fputs(text: C.String, stream: Stream) -> C.Int32
compute def fflush(stream: Stream) -> C.Int32
def isatty(fd: C.Int32) -> C.Int32
end
## Opens a file for appending, or says which path failed.
def open_append(path: String) -> Result[Stream]
case fopen(path, "a")
Result.Ok(stream) -> ok(stream)
Result.Err(_) -> error("cannot open #{path}")
end
end
## Writes one line.
def write_line(stream: Stream, text: String) -> Result[Void]
return error("cannot write to the stream") if fputs("#{text}\n", stream) < 0
ok()
end
## Pushes the buffered text to the file.
def flush(stream: Stream) -> Result[Void]
return error("cannot flush the stream") if fflush(stream) != 0
ok()
end
## True when the descriptor is a terminal.
def tty?(fd: Int) -> Bool = isatty(fd) == 1fopen is declared -> Stream, so the raw call already gives a Result[Stream]. The wrapper only replaces its message with one that names the path. Stream is public, so callers can name the type. Callers close the stream with Native.close, or the task that owns it frees it when it ends. fflush is a compute def in the raw layer, and flush calls it like any function.
Out parameters #
An out parameter stays in the raw layer: the wrapper copies the record fields into a struct of its own.
struct Split
whole: Float
fraction: Float
end
## Splits x into its whole part and its fraction, both with the sign of x.
def split(x: Float) -> Split
parts = modf(x)
Split(whole: parts.whole, fraction: parts.result)
end
private
extern "libm.so.6"
def modf(x: C.Double, out whole: C.Double) -> C.Double
endBuffers and block forms #
A C function that fills memory its caller gives it, such as getcwd, gets an owned buffer. The wrapper makes it with the block form, Native.memory_pointer(size) do |buf| ... end, which frees the buffer when the block ends, also when the block returns an error early, and returns the block’s value. The block copies out what C wrote, so the caller gets a String or a List and never sees the buffer.
## The working directory, or an error when it is longer than 4095 bytes.
def cwd() -> Result[String]
Native.memory_pointer(4096) do |buf|
return error("the working directory is longer than 4095 bytes") if Native.null?(getcwd(buf, 4096))
ok(Native.get_string(buf, 0))
end
end
private
extern "libc.so.6"
def getcwd(buf: C.Pointer, size: C.Int64) -> C.Pointer
endA wrapper may give a resource a block form of its own, as Ruby’s File.open does: it opens the resource, gives it to the block, closes it when the block ends and returns what the block returned, so the caller cannot forget the close. If the block stops with a runtime error, the end of the task frees the resource.
extern "libc.so.6"
resource Stream, free: fclose
def fopen(path: C.String, mode: C.String) -> Stream
def fputs(text: C.String, stream: Stream) -> C.Int32
end
## Opens a file for appending, gives the stream to the block and closes it when the block ends.
def append_to(path: String, f: Fn[Stream, Result[Void]]) -> Result[Void]
stream = try fopen(path, "a")
done = f.call(stream)
Native.close(stream)
done
end
def main() -> Void
written = append_to("/tmp/agentica-log.txt") do |stream|
return error("cannot write the log") if fputs("started\n", stream) < 0
ok()
end
IO.inspect(written)
endVariadic functions #
Agentica functions have no variadic parameters, and a wrapper does not add any. Declare the C function once for each shape that your wrapper needs, with ... and = "symbol", and keep the shapes private. The public function takes a normal parameter instead:
- Parameters with defaults, when an argument is optional (
on: Bool = true). - A struct, when there are many options. Give its fields default values. The caller names only the fields that differ:
OpenOptions(create: true), orOpenOptions()for all the defaults. - A
List[T], when the count of arguments changes. The wrapper picks the shape from the length of the list and returns anerrorfor a length it has no shape for.
## Read only by default, and mode 0600 when the file is created.
struct OpenOptions
write: Bool = false
create: Bool = false
mode: Int = 384
end
## Opens a file and gives its descriptor.
def open_file(path: String, options: OpenOptions) -> Result[Int]
flags = 0
if options.write
flags = flags + O_WRONLY
end
if options.create
flags = flags + O_CREAT
end
fd = open(path, flags, options.mode)
return error("cannot open #{path}") if fd < 0
ok(fd)
end
## Sets or clears close-on-exec.
def set_close_on_exec(fd: Int, on: Bool = true) -> Result[Void]
flag = 0
if on
flag = FD_CLOEXEC
end
return error("cannot set close-on-exec on #{fd}") if fcntl_set(fd, F_SETFD, flag) < 0
ok()
end
## Writes one or two fields to fd, separated by a tab and ended by a newline.
def write_fields(fd: Int, fields: List[String]) -> Result[Void]
written = -1
if fields.length == 1
written = dprintf1(fd, "%s\n", fields[0])
elsif fields.length == 2
written = dprintf2(fd, "%s\t%s\n", fields[0], fields[1])
end
return error("cannot write #{fields.length} fields to #{fd}") if written < 0
ok()
end
private
O_WRONLY = 1
O_CREAT = 64 # the Linux value; macOS uses 0x200
F_SETFD = 2
FD_CLOEXEC = 1
extern "libc.so.6"
def open(path: C.String, flags: C.Int32, ..., mode: C.Int32) -> C.Int32
def fcntl_set(fd: C.Int32, cmd: C.Int32, ..., arg: C.Int32) -> C.Int32 = "fcntl"
def dprintf1(fd: C.Int32, format: C.String, ..., a: C.String) -> C.Int32 = "dprintf"
def dprintf2(fd: C.Int32, format: C.String, ..., a: C.String, b: C.String) -> C.Int32 = "dprintf"
endopen_file gives a descriptor; the example leaves out a function that closes it. write_fields never lets its caller choose the format. The format is a constant of the wrapper, and the caller’s text goes in as %s arguments, so a % in a field is only text.
Structs of options #
Some libraries take their options as a struct by value, with a function that gives the defaults: llama.cpp has llama_context_default_params() and llama_init_from_model(model, params). The raw layer declares the C struct in the block, every field in the order of the header (C structs). The wrapper takes the defaults, sets the fields that the caller chose with .with, and passes the record on. The caller sees only a struct of its own, with the options it may set.
struct ContextOptions
size: Int = 4096
threads: Int = 4
end
extern "/opt/infer/libinfer.so"
resource Model, free: infer_model_free
resource Context, free: infer_free
struct ContextParams
n_ctx: C.Int32
n_batch: C.Int32
n_threads: C.Int32
rope_freq_base: C.Float
embeddings: C.Bool
offload: C.Bool
callback_data: C.Pointer
end
def infer_context_default_params() -> ContextParams
compute def infer_init_from_model(model: Model, params: ContextParams) -> Context
end
## A context of the model with the caller's options; the other parameters keep the library's defaults.
def context(model: Model, options: ContextOptions) -> Result[Context]
params = infer_context_default_params().with(n_ctx: options.size, n_threads: options.threads)
case infer_init_from_model(model, params)
Result.Ok(made) -> ok(made)
Result.Err(_) -> error("cannot make a context of #{options.size} tokens")
end
endA size that does not fit in a C.Int32 stops the program at the call (RUNTIME-INTEGER-OVERFLOW), so a wrapper that must not stop checks the options first; the example skips that check.
Tables of function pointers #
A library whose API is a struct of function pointers, such as onnxruntime, is wrapped the same way. The raw layer declares each slot that the wrapper uses as a def whose first parameter is fn: C.Function, and each handle as resource Name, free: C.Function, freed through the release slot of the table. The wrapper gets the table once, keeps the slot numbers as constants in the order of the C header, and passes Native.get_pointer(api, slot * 8) to the raw defs, so the caller never sees a function pointer. A slot number from another version of the header is undefined behavior, like a wrong signature: ask for the version the slots come from, as onnxruntime’s GetApi(version) does, and turn its NULL into an error.
Shipping it in a package #
A package names the library for each system in [native.NAME] of its agentica.toml. Its extern block then opens it with extern "NAME". See the modules reference for the form, the lock and the error codes. Document the wrapper file as the API of the package.