Foreign Function Interface (FFI)

The ffi module provides a foreign function interface for ucode, allowing direct interaction with C libraries. It combines a C declaration parser with libffi-based function calling to enable seamless interop between ucode and C.

The module can be imported using the wildcard import syntax:

import * as ffi from 'ffi';

Synopsis

import * as ffi from 'ffi';

// 1. Declare C types and functions
ffi.cdef(`
    struct point { int x; int y; };
    extern char **environ;
`);

// 2. Call C functions via the global C namespace
// Primitive return values are auto-converted to ucode types
let strcmp = ffi.C.wrap('int strcmp(const char *, const char *)');
print(strcmp("hello", "world"), "\n");  // => non-zero (number)

// 3. String return values remain as cdata - use ffi.string() to convert
let getenv = ffi.C.wrap('char *getenv(char *)');
let path_ptr = getenv('PATH');      // Returns char* cdata
let path_str = ffi.string(path_ptr); // Convert to ucode string

// 4. Create C data instances
ffi.cdef('struct point { int x; int y; };');
let p = ffi.ctype('struct point', 10, 20);
print(p.get('x'), p.get('y'), "\n");  // => 10 20

// 5. Access global variables
print(ffi.C.dlsym('environ').get(0), "\n");

// 6. Query type information
print(ffi.sizeof('int'), "\n");        // => 4
print(ffi.alignof('double'), "\n");    // => 8
print(ffi.offsetof('struct point', 'y'), "\n");  // => 4

// 7. Load external libraries
let libz = ffi.dlopen('z');
let zlibVersion = libz.wrap('const char *zlibVersion(void)');
print(zlibVersion().slice(), "\n");  // => "1.2.11" (or similar)

// Use in callbacks (primitives auto-converted)
let qsort = ffi.C.wrap('void qsort(void *, size_t, size_t, int (*)(const void *, const void *))');
let cmp = ffi.C.wrap('int strcmp(const char *, const char *)');
let arr = ffi.ctype('char *[5]', ["zebra", "apple", "banana", "cherry", "date"]);
// cmp() returns ucode number directly (primitives auto-converted)
qsort(arr.ptr(), arr.length(), arr.itemsize(),
      (a, b) => cmp(a.deref('const char *'), b.deref('const char *')));

Memory Management for char* Return Values

When a wrapped C function returns char*, the return value is a cdata pointer object, not an auto-converted ucode string. This design prevents memory leaks and gives you explicit control over memory management.

Converting char* to ucode Strings

Use ffi.string() or slice() to convert a char* cdata to a ucode string:

let getenv = ffi.C.wrap('char *getenv(char *)');

let path_ptr = getenv('PATH');    // Returns char* cdata
let path = ffi.string(path_ptr);  // Convert to ucode string
// or equivalently:
let path = path_ptr.slice();      // slice() without args = string()

Note: Both ffi.string() and slice() create a copy of the C string. The original C memory remains untouched.

Memory Ownership Patterns

Pattern 1: C Manages Memory (No Free Required)

Functions like getenv(), strerror() return pointers to static/internal memory managed by the C library. Do NOT free these.

let getenv = ffi.C.wrap('char *getenv(char *)');

let path_ptr = getenv('PATH');
let path = ffi.string(path_ptr);  // Copies to ucode string

// path_ptr points to C internal memory - DO NOT free
// path is a ucode string - managed by ucode GC

Pattern 2: Caller Must Free (malloc'd Memory)

Functions like strdup(), asprintf(), getline() return malloc'd memory that you must free to avoid leaks.

let strdup = ffi.C.wrap('char *strdup(const char *)');
let free = ffi.C.wrap('void free(void *)');

let ptr = strdup("hello");      // malloc'd by strdup
let str = ffi.string(ptr);      // Copies to ucode string
free(ptr);                       // NOW you can safely free

// str is safe - it's a ucode string copy
// ptr memory is freed - no leak

Key: Keep the cdata pointer until you're done copying, then free it.

Pattern 3: Stack-Allocated Buffers

When C writes into a buffer you provide (e.g., sprintf), the buffer is managed by ucode.

let sprintf = ffi.C.wrap('int sprintf(char *, const char *, ...)');

let buf = ffi.ctype('char[256]');  // ucode-managed array
sprintf(buf, "Hello %s", "World");

let msg = ffi.string(buf);  // Copies to ucode string

// buf is managed by ucode GC - no manual free needed

Substring Operations with slice()

For char* pointers, slice() supports substring extraction:

let getenv = ffi.C.wrap('char *getenv(char *)');
let ptr = getenv('PATH');

// From start to end (same as ffi.string())
let full = ptr.slice();

// From start index to end
let rest = ptr.slice(5);

// Specific range
let part = ptr.slice(0, 10);

// Negative indices (from end)
let last = ptr.slice(-5);

Common Functions Reference

Best Practices

1. Always use ffi.string() or slice() when you need a ucode string from char*
2. Track ownership: Does C manage the memory or do you?
3. Free after copying: Call free(ptr) only after ffi.string(ptr) or ptr.slice()
4. Never free static memory: getenv(), strerror() return static pointers

Limitations

• No vararg closures: wrap() cannot create closures with variable arguments
• Fixed ABI: Calling convention determined at closure creation time
• Platform constraints: Some architectures have limited support for certain type combinations

The ffi.C Namespace

ffi.C is a special CLib instance representing the process's global symbol table. It provides access to standard C library functions without explicit dlopen():

// These are equivalent:
let strlen1 = ffi.C.wrap('size_t strlen(const char *)');

ffi.cdef('size_t strlen(const char *);');
let strlen2 = ffi.C.wrap('strlen');

Functions declared via cdef() are automatically registered in ffi.C's symbol table.

Pointer Arithmetic and Memory Access

C data objects (cdata) provide methods for pointer arithmetic and memory access:

Creating Pointers with ptr()

Use ptr() to get a pointer to a cdata value:

let x = ffi.ctype('int', 42);
let px = x.ptr();  // int* pointer to x

// Pass to C functions expecting pointers
ffi.cdef('int atoi(const char *)');
let num = ffi.ctype('char[4]', "123");
let result = atoi(num.ptr());  // => 123

Array Indexing with get() and set()

Access array elements using get(index) and set(index, value):

let arr = ffi.ctype('int[5]', [10, 20, 30, 40, 50]);

// Read elements
let first = arr.get(0);  // => 10 (ucode number)
let third = arr.get(2);  // => 30 (ucode number)

// Modify elements
arr.set(0, 100);
arr.set(4, 200);

// Negative indices work too
let last = arr.get(-1);  // => 200 (ucode number)

Understanding get() vs index()

get() returns converted ucode values, while index() returns raw cdata references. This is the key distinction between the two methods.

get() - Converted Values

The get() method immediately converts C values to ucode types:

let arr = ffi.ctype('int[5]', [10, 20, 30, 40, 50]);

// Returns ucode number directly
let val1 = arr.get(0);      // => 10 (number)
let val2 = arr.get(2);      // => 30 (number)

// Struct field access - returns converted value
ffi.cdef('struct point { int x; int y; };');
let p = ffi.ctype('struct point', 10, 20);
p.get('x');      // => 10 (number)
p.get('y');      // => 20 (number)

index() - Raw cdata References

The index() method returns a cdata reference for further manipulation:

let arr = ffi.ctype('int[5]', [10, 20, 30, 40, 50]);

// Returns cdata reference (unconverted)
let ref1 = arr.index(0);    // => cdata (int)
let ref2 = arr.index(2);    // => cdata (int)

// Convert to ucode value explicitly
ref1.get();     // => 10 (number)

// Or modify through the reference
arr.index(0).set(100);  // Set arr[0] = 100

Pointer Arithmetic

Both methods work with pointers, but return different types:

let ptr = ffi.ctype('int *', arr.ptr());

// index() returns cdata reference
ptr.index(0);   // => cdata at ptr[0]
ptr.index(1);   // => cdata at ptr[1]
ptr.index(0).get();  // => 10 (number)

// get() returns converted value
ptr.get(0);     // => 10 (number)
ptr.get(1);     // => 20 (number)

Path Syntax Support

Both methods support path notation for nested access:

ffi.cdef('struct rect { struct point min; struct point max; };');
let r = ffi.ctype('struct rect', {
    min: {x: 0, y: 0},
    max: {x: 100, y: 100}
});

// get() returns converted value
r.get('min.x');       // => 0 (number)

// index() returns cdata reference
r.index('min.x');     // => cdata (int)
r.index('min.x').get() // => 0 (number)

Practical Guidance

Use get() when:

• You need the value immediately as a ucode type
• Reading values for computation: let x = arr.get(i)
• Accessing struct fields: let y = struct.get('field')
• Most common use cases

Use index() when:

• You need a reference for further manipulation
• Chaining operations: arr.index(i).set(val)
• Pointer arithmetic with cdata: ptr.index(n).deref()
• Passing references to other C functions

For writing values:

• Use set() for both arrays and structs: arr.set(i, val), struct.set('f', val)

For getting pointers (not values):

• Use ptr() on scalars: x.ptr() gives you int*
• Arrays are already pointers: arr can be passed to C functions

Pointer Arithmetic via get() and index()

Both get(n) and index(n) work for pointer arithmetic on pointer types:

ffi.cdef('char *strdup(const char *)');
let strdup = ffi.C.wrap('char *strdup(const char *)');

let ptr = strdup("hello world");

// get() returns converted value (number for char)
let first_char = ptr.get(0);    // 'h' (number 104)
let sixth_char = ptr.get(6);    // 'w' (number 119)

// index() returns cdata reference
ptr.index(6);       // => cdata (char)
ptr.index(6).get()  // => 119 (number)

// Get substring from offset
let substring = ffi.string(ptr.get(6));  // "world"

free(ptr);

Path-Based Access for Nested Structures

Use dot notation and array indexing in paths for complex access:

ffi.cdef(`
    struct point { int x; int y; };
    struct rect { struct point min; struct point max; };
`);

let r = ffi.ctype('struct rect', {
    min: {x: 0, y: 0},
    max: {x: 100, y: 100}
});

// Nested field access
r.get('min.x');    // => 0
r.set('max.y', 50);

// Array of structs
ffi.cdef('struct point points[3];');
let arr = ffi.ctype('struct point[3]', [
    {x: 1, y: 2},
    {x: 3, y: 4},
    {x: 5, y: 6}
]);

arr.get('[1].x');  // => 3
arr.set('[2].y', 10);

Dereferencing Pointers with deref()

Use deref(type) to read the value pointed to:

let x = ffi.ctype('int', 42);
let px = x.ptr();

let value = px.deref('int');  // => 42

// With char* pointers
ffi.cdef('char *strdup(const char *)');
let strdup = ffi.C.wrap('char *strdup(const char *)');

let ptr = strdup("hello");
let first_byte = ptr.deref('char');  // => 'h' (as number 104)

free(ptr);

Querying Array Properties

Use length() and itemsize() for array information:

let arr = ffi.ctype('int[10]');

arr.length();   // => 10 (number of elements)
arr.itemsize(); // => 4 (size of each element in bytes)

// Calculate total size
let total = arr.length() * arr.itemsize();  // => 40 bytes

Working with Byte Arrays

For char[] or uint8_t[], use slice() to extract strings:

let buf = ffi.ctype('char[10]', "hello");

// Extract as ucode string
let str = buf.slice();        // => "hello"
let part = buf.slice(0, 3);   // => "hel"

// Or use ffi.string()
let str2 = ffi.string(buf);   // => "hello"

Complete Example: String Manipulation

ffi.cdef(`
    char *strdup(const char *);
    void free(void *);
    size_t strlen(const char *);
`);

let strdup = ffi.C.wrap('char *strdup(const char *)');
let free = ffi.C.wrap('void free(void *)');
let strlen = ffi.C.wrap('size_t strlen(const char *)');

// Create a duplicatable string
let ptr = strdup("hello world");

// Get length
let len = strlen(ptr).get();  // => 11

// Access individual characters via indexing
let first = ptr.get(0);       // 'h'
let sixth = ptr.get(6);       // 'w'

// Extract substrings
let hello = ptr.slice(0, 5);  // "hello"
let world = ptr.slice(6);     // "world"

// Modify in place
ptr.set(5, 0);  // Null-terminate at space

let str = ffi.string(ptr);  // => "hello"

// Clean up
free(ptr);