mirror of
https://github.com/lune-org/docs.git
synced 2025-04-04 18:40:59 +01:00
115 lines
3.2 KiB
Text
115 lines
3.2 KiB
Text
import { FileTree, Tabs, Tab, Callout } from 'nextra/components'
|
|
|
|
# FFI
|
|
|
|
Luna has built-in library for handling foreign function, [`ffi`](../../api-reference/ffi.md).
|
|
This library will let you call external function, allocate memories with specific size and value, create closures, and more.
|
|
|
|
## Example File Tree
|
|
|
|
Let's use this directly & file tree sturcture for our examples:
|
|
|
|
<FileTree>
|
|
<FileTree.Folder name="-" defaultOpen>
|
|
<FileTree.File name="call.luau" />
|
|
<FileTree.File name="closure.luau" />
|
|
<FileTree.Folder name="external" defaultOpen>
|
|
<FileTree.File name="lib.c" />
|
|
<FileTree.File name="lib.so" />
|
|
</FileTree.Folder>
|
|
</FileTree.Folder>
|
|
</FileTree>
|
|
|
|
<details>
|
|
<summary>Show file contents</summary>
|
|
|
|
```c copy filename="external/lib.c"
|
|
int addNumber(int a, int *b) {
|
|
return a + *b;
|
|
}
|
|
|
|
typedef int(*closure_t)(int, int*);
|
|
int callClosure(closure_t closure) {
|
|
int b = 200;
|
|
return closure(100, &b) * 2;
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<Callout type="info" emoji="❔">
|
|
To create the `external/lib.so` file, you will need a C compiler like `gcc`. Run c compiler with the following command: `gcc -shared -o external/lib.so -fPIC external/lib.c`.
|
|
</Callout>
|
|
|
|
## Call external function
|
|
|
|
```lua copy filename="call.luau"
|
|
local ffi = require("@lune/ffi")
|
|
local c = ffi.c
|
|
|
|
--> Open dynamic library
|
|
local lib = ffi.open("./external/lib.so")
|
|
|
|
--> Create function signature
|
|
local addNumberInfo = c.fn({ c.int, c.int:ptr() }, c.int)
|
|
|
|
--> Get symbol from library and create callable
|
|
local addNumber = addNumberInfo:callable(lib:find("addNumber"))
|
|
|
|
--> Create memory for result
|
|
local resultBox = ffi.box(c.int.size)
|
|
|
|
--> Create arguments
|
|
local aBox = c.int:box(100)
|
|
local bBox = c.int:box(200)
|
|
|
|
--> Call external function. all arguments should be references.
|
|
--> If you want to pass a pointer as argument, call `:ref()` again.
|
|
addNumber(resultBox, aBox:ref(), bBox:ref():ref())
|
|
|
|
--> Read number from resultBox
|
|
local result = c.int:readData(resultBox)
|
|
print(result) -- 300
|
|
```
|
|
|
|
Note that All data is automatically freed by the garbage collector. If external function stores pointer in somewhere or frees pointer, you should call `:leak()` to leak it.
|
|
|
|
## Create closure from lua function
|
|
|
|
```lua copy filename="closure.luau"
|
|
local ffi = require("@lune/ffi")
|
|
local c = ffi.c
|
|
|
|
--> Open dynamic library
|
|
local lib = ffi.open("./external/lib.so")
|
|
|
|
--> Create closure function signature
|
|
local closureInfo = c.fn({ c.int, c.int:ptr() }, c.int)
|
|
|
|
--> Create closure with lua function
|
|
local closure = closureInfo:closure(function(resultRef, aRef, bRefRef)
|
|
--> Convert arguments to lua number
|
|
local a = c.int:readData(aRef)
|
|
local b = c.int:readData(bRefRef:deref())
|
|
|
|
--> Write a+b into result reference
|
|
c.int:writeData(resultRef, a + b)
|
|
print("Closure returned: " .. (a + b))
|
|
end)
|
|
|
|
--> Create callClosure function signature
|
|
local callClosureInfo = c.fn({ closureInfo }, c.int)
|
|
|
|
--> Get symbol from library and create callable
|
|
local callClosure = callClosureInfo:callable(lib:find("callClosure"))
|
|
|
|
--> Create memory for result
|
|
local resultBox = ffi.box(c.int.size)
|
|
|
|
--> Call external function.
|
|
callClosure(resultBox, closure:ref())
|
|
|
|
--> Read number from resultBox
|
|
local result = c.int:readData(resultBox)
|
|
print(result) -- 600
|
|
```
|