For the complete Mojo documentation index, see llms.txt. Markdown versions of all pages are available by appending .md to any URL (e.g. /docs/manual/basics.md).
Passing data to exported Mojo functions
A Mojo library exports functions with @export and abi("C"), and foreign
code calls them like any other C function. These examples show the Mojo
side in full, with a short C, C++, or Rust caller. C-compatible data
types explains the types and ownership
rules they use. To build the library and link a caller, see Example: Call
Mojo from
C.
Opaque handles
Foreign code holds a handle and passes it back.
Export one function that creates a value and one that destroys it. In
this example, Stats is an ordinary Mojo struct that keeps a running count
and mean:
from std.memory.alloc import alloc, dealloc, Allocation, Layout
@fieldwise_init
struct Stats:
var count: Int
var mean: Float64
comptime Handle = MutOpaquePointer[MutUntrackedOrigin]
@export("stats_new")
def stats_new() abi("C") -> Handle:
var stats = alloc(Layout[Stats].single()).unsafe_leak()
stats.write(Stats(count=0, mean=0.0))
return stats.unsafe_bitcast[NoneType]()
@export("stats_free")
def stats_free(handle: Handle) abi("C"):
dealloc(Allocation(
unsafe_owned_ptr=handle.unsafe_bitcast[Stats](),
layout=Layout[Stats].single(),
))
alloc() returns an Allocation. Mojo makes you dispose of an
Allocation explicitly, so its memory can't leak by accident.
unsafe_leak() disposes of it by handing the memory to the foreign caller.
stats_free() takes ownership back by rebuilding the Allocation, and
dealloc() frees the memory.
Other exports, such as a stats_add() that records a value, turn the
handle back into a Stats pointer with unsafe_bitcast[Stats](). Nothing
checks that the handle really points to a Stats.
A C++ caller declares Stats without defining it, so it can't see inside.
It lets unique_ptr call stats_free() when the handle goes out of scope:
extern "C" {
struct Stats;
Stats *stats_new(void);
double stats_add(Stats *stats, double value);
void stats_free(Stats *stats);
}
std::unique_ptr<Stats, decltype(&stats_free)> stats(stats_new(), stats_free);
Foreign code frees the handle with your exported function, never with its
own free() or delete. Those don't know how Mojo allocated the memory.
Structs
The Mojo side declares the fields in C order and exports a function that takes the struct:
from std.math import sqrt
@fieldwise_init
struct Point:
var x: Float64
var y: Float64
@export("distance")
def distance(a: Point, b: Point) abi("C") -> Float64:
return sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
Rust gives a struct C's layout with #[repr(C)]:
#[repr(C)]
struct Point { x: f64, y: f64 }
unsafe extern "C" {
fn distance(a: Point, b: Point) -> f64;
}
The two struct definitions form the contract. Nothing compares them. If a field changes on one side and not the other, you get wrong values, not an error.
Arrays
The Mojo side views the elements as a Span for the length of the call:
from std.ffi import c_size_t
from std.math import sqrt
@export("rms")
def rms(
samples: Pointer[Float32, ImmUntrackedOrigin], count: c_size_t
) abi("C") -> Float64:
var total: Float64 = 0
for sample in Span(unsafe_ptr=samples, length=Int(count)):
total += Float64(sample) ** 2
return sqrt(total / Float64(count))
A C++ caller passes a std::vector's data() and size():
extern "C" double rms(const float *samples, size_t count);
std::vector<float> samples = {3.0f, -4.0f, 3.0f, -4.0f};
// An empty vector's data() can be null, and rms() takes a non-null pointer.
double level = samples.empty() ? 0.0 : rms(samples.data(), samples.size());
The caller owns the samples. Read them during the call, and don't keep the
pointer or the span after rms() returns. Once the call ends, the caller
can grow the vector or destroy it.
Strings
An exported function that takes a const char* receives a view that the
caller owns. Read it during the call, and copy anything you need to keep.
An exported function that returns a new string allocates it with
alloc(), copies in the bytes and a terminating zero, and returns the
pointer from unsafe_leak(). Foreign code can't release that memory with
its own free(), so export a matching free function for it to call once
per string. dealloc() needs the allocation's length, and the free
function recovers it by counting up to the terminating zero.
Callbacks
A Mojo library that accepts a callback follows C's convention: it takes a
void* context with the callback and passes the context back unchanged.
This exported function runs a computation in steps and reports its
progress after each one:
from std.ffi import c_double, c_int
from std.math import pi, sin
comptime Context = MutOpaquePointer[MutUntrackedOrigin]
comptime Progress = def(c_double, Context) thin abi("C")
@export("integrate_sin")
def integrate_sin(
steps: c_int, progress: Progress, context: Context
) abi("C") -> c_double:
var width = pi / Float64(steps)
var area: Float64 = 0
for i in range(Int(steps)):
area += sin((Float64(i) + 0.5) * width) * width
progress(Float64(i + 1) / Float64(steps), context)
return area
A C caller passes its callback and a pointer to its own state:
static void report(double fraction, void *context) {
int *calls = context;
++*calls;
printf("%.0f%%\n", fraction * 100);
}
int calls = 0;
double area = integrate_sin(4, report, &calls);
The caller owns the context. Mojo never reads it, and hands it back only
during the call to integrate_sin(). Nothing checks that the callback's
signature in C matches Progress in Mojo. A mismatch produces undefined
behavior, not an error.
Errors
An exported function marked abi("C") can't raise. Handle errors inside
the function, and report them the C way: return a status code, return a
null pointer, or send the details through a C-style out argument.