From 2d2848cb907961a73403118a57e65c9512282a33 Mon Sep 17 00:00:00 2001 From: qwreey Date: Thu, 24 Oct 2024 04:45:34 +0000 Subject: [PATCH 1/2] Add getting started page for ffi (#17) --- .../getting-started/2-introduction/11-ffi.mdx | 115 ++++++++++++++++++ .../getting-started/2-introduction/_meta.json | 3 +- 2 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 pages/getting-started/2-introduction/11-ffi.mdx diff --git a/pages/getting-started/2-introduction/11-ffi.mdx b/pages/getting-started/2-introduction/11-ffi.mdx new file mode 100644 index 0000000..6cde0d4 --- /dev/null +++ b/pages/getting-started/2-introduction/11-ffi.mdx @@ -0,0 +1,115 @@ +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: + + + + + + + + + + + + +
+Show file contents + +```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; + } +``` + +
+ + + 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`. + + +## 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.c") + +--> 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="call.luau" +local ffi = require("@lune/ffi") +local c = ffi.c + +--> Open dynamic library +local lib = ffi.open("./external/lib.c") + +--> 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) -- 300 +``` diff --git a/pages/getting-started/2-introduction/_meta.json b/pages/getting-started/2-introduction/_meta.json index 0aa48b1..414b2bf 100644 --- a/pages/getting-started/2-introduction/_meta.json +++ b/pages/getting-started/2-introduction/_meta.json @@ -8,5 +8,6 @@ "7-environment-variables": "7 • Environment Variables", "8-modules": "8 • Modules", "9-task-scheduler": "9 • Task Scheduler", - "10-spawning-processes": "10 • Spawning Processes" + "10-spawning-processes": "10 • Spawning Processes", + "11-ffi": "11 • Foreign Function Interface" } From ac5df79a0905db574306ea0a90322fbd7dcb94c0 Mon Sep 17 00:00:00 2001 From: qwreey Date: Thu, 24 Oct 2024 06:02:57 +0000 Subject: [PATCH 2/2] Fix ffi getting started example (#17) --- pages/getting-started/2-introduction/11-ffi.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pages/getting-started/2-introduction/11-ffi.mdx b/pages/getting-started/2-introduction/11-ffi.mdx index 6cde0d4..aa3da80 100644 --- a/pages/getting-started/2-introduction/11-ffi.mdx +++ b/pages/getting-started/2-introduction/11-ffi.mdx @@ -23,17 +23,17 @@ Let's use this directly & file tree sturcture for our examples:
Show file contents -```c copy filename="external/lib.c" + ```c copy filename="external/lib.c" int addNumber(int a, int *b) { - return a + b; + return a + *b; } - typedef int(*closure_t)(int, int); + typedef int(*closure_t)(int, int*); int callClosure(closure_t closure) { int b = 200; return closure(100, &b) * 2; } -``` + ```
@@ -48,7 +48,7 @@ local ffi = require("@lune/ffi") local c = ffi.c --> Open dynamic library -local lib = ffi.open("./external/lib.c") +local lib = ffi.open("./external/lib.so") --> Create function signature local addNumberInfo = c.fn({ c.int, c.int:ptr() }, c.int) @@ -76,12 +76,12 @@ Note that All data is automatically freed by the garbage collector. If external ## Create closure from lua function -```lua copy filename="call.luau" +```lua copy filename="closure.luau" local ffi = require("@lune/ffi") local c = ffi.c --> Open dynamic library -local lib = ffi.open("./external/lib.c") +local lib = ffi.open("./external/lib.so") --> Create closure function signature local closureInfo = c.fn({ c.int, c.int:ptr() }, c.int) @@ -111,5 +111,5 @@ callClosure(resultBox, closure:ref()) --> Read number from resultBox local result = c.int:readData(resultBox) -print(result) -- 300 +print(result) -- 600 ```