BQN's foreign function interface allows it to interface with libraries written in C, or other languages that support a compatible format. It's invoked with •FFI, which performs the necessary lookups and conversions to call a function from a dynamic shared library (extension .so in Unix-like systems and .dll in Windows). This function is specified by BQN and implemented by CBQN—without support for all possible types, but enough for practical use.
BQN's foreign function interface allows it to interface with libraries written in C, or other languages that support a compatible format. It's invoked with •FFI, which performs the necessary lookups and conversions to call a function from a dynamic shared library (extension .so in Linux, .dylib in macOS, and .dll in Windows). This function is specified by BQN and implemented by CBQN—without support for all possible types, but enough to cover practical use well.
Warning: object code is unsafe by nature. The OS will hopefully prevent it from exceeding the privileges of the BQN interpreter, but anything code in the interpreter could do is fair game. It might crash, write files, corrupt BQN arrays resulting in "impossible" behavior later on, or read everything in your home directory and email it to someone. Be careful when invoking the FFI!
•FFI takes the path of the object file as 𝕨, with local paths resolved relative to the source file as in •Import. 𝕩 describes the specific function requested from this file and its type signature, and the result is a BQN function that calls it. While a major purpose of •FFI is to be called with files like libpng.so that you may already have on your system, we'll start by writing some C to make it clear what's happening on both sides of the interface. A factorial function is pretty short, so let's start there:
The cycles are 0, 124, and 3, so that checks out. But cycles modifies its argument p, with the line p[j] = i. Is the BQN list p changed when this happens? The check on the last line says no, which is good because BQN arrays are supposed to be immutable. What happens is that BQN copies the data into temporary memory in order to pass it in to C (here it also converts from 8 bits for each element to 32).
But what if we want to see those modifications? Many C functions use pointer modification as a way to return multiple values, so the FFI supports this. With & instead of *, the values after calling the function are returned as an extra result.
The cycles are 0, 124, and 3, so that checks out. But cycles modifies its argument p, with the line p[j] = i. Is the BQN list p changed when this happens? The check on the last line says no, which is good because BQN arrays are supposed to be immutable. What happens in this case is that CBQN stores p with 8 bits per element, so to widen it to 32 bits it copies to temporary memory. And in fact CBQN assumes the C function won't modify a *-typed argument, so to avoid issues in the case that p does have 32-bit elements it should be passed in as ≠⊸⋈ •internal.Unshare p.
But what if we want to see the modifications? Many C functions use pointer modification as a way to return multiple values, so the FFI supports this. With & instead of *, the values after calling the function are returned as an extra result (and the original argument is always copied to avoid changes to aliased values).
cycles ← "cyc.so" •FFI "u32"‿"cycles"‿"u32"‿"&u32" •Show Cycles ≠⊸⋈ ⍋"cycle" # ⟨ 3 ⟨ 0 1 1 3 1 ⟩ ⟩-
The original result might not be wanted in this case. You can ignore it by using "" for the result type, but then you get a 1-element list, for consistency with the case with multiple & arguments. Similar to > on a single argument, you can use "&" for the result to get a single mutated argument returned directly.
The original result might not be wanted in this case. You can ignore it (relying on u32 not being stack-allocated!) by using "" for the result type, but then you get a 1-element list, for consistency with the case with multiple & arguments. Similar to > on a single argument, you can use "&" for the result to get a single mutated argument returned directly.
cycI ← "cyc.so" •FFI "&"‿"cycles"‿"u32"‿"&u32" •Show CycI ≠⊸⋈ ⍋"cycle" # ⟨ 0 1 1 3 1 ⟩@@ -73,17 +73,18 @@
So what do all these C types mean in BQN? The FFI tries to define sensible conversions. But BQN can't always represent every value directly, so it also provides explicit conversions with : using the underlying bit representation, giving a way to safely store any value.
On to implicit conversions, let's start with numbers. CBQN numbers are 64-bit floats, which are a superset of integer types up to 32 bits, and 32-bit floats. So conversions from all these types are exact with no problems. Converting to a smaller integer type requires the float value to fit in that type, while converting to a smaller float type rounds.
-Issues show up with 64-bit integer types because 64-bit floats only have full integer precision from -2⋆53 to 2⋆53. Some integers beyond this range are representable, but others aren't: for example 1+2⋆53 rounds to 2⋆53. For this reason numbers with absolute value 2⋆53 and greater error when converting between float and integer. Bare u64 and i64 types are fine when working with lengths and other things that can't reasonably be that large, but when all the bits are used they should be converted with i64:u32 or similar.
Issues show up with 64-bit integer types because 64-bit floats only have full integer precision from -2⋆53 to 2⋆53. Some integers beyond this range are representable, but others aren't: for example 1+2⋆53 rounds to 2⋆53. For this reason numbers with absolute value 2⋆53 and greater error when converting between float and integer. Bare u64 and i64 types are fine when working with lengths and other things that can't reasonably be that large, but when all the bits are used they should be converted with u64:i32 or similar.
An array or struct corresponds to a BQN list, easy enough.
-A BQN list or pointer object can be converted to a pointer, and a C pointer is always converted to a pointer object—it can't be converted to a list because the length is unknown, but sometimes a mutable pointer is a convenient way to get a list from a C function. Pointer objects are BQN values designed specifically to encapsulate C pointers. If passed as an argument, its type needs to be compatible with the type for that argument, if it has one. When an argument has an untyped pointer type * or &, it can't take a list as input (what would the elements be converted to?) but any pointer object will be accepted.
A BQN list or pointer object can be converted to a pointer, and a C pointer is always converted to a pointer object—it can't be converted to a list because the length is unknown, but sometimes a mutable pointer is a convenient way to get a list from a C function. Pointer objects are BQN values designed specifically to encapsulate C pointers. If passed as an argument, its type needs to be compatible with the type for that argument, if it has one.
+When an argument has an untyped pointer type * or &, it can't take a list as input (what would the elements be converted to?) but any pointer object will be accepted. Since an untyped pointer isn't a list of anything, it's treated more like a scalar value. In particular a type like *:i32 converts a pointer back and forth from two integers.
Either the type as a whole, or any member of a struct, can have a conversion specification like :u32 at the end. The type after the colon uses the same format as C numeric types, with the quality c allowed for characters in addition to i, u, and f. Here CBQN supports the types it uses internally for arrays: u1 for booleans, i8 to i32 and c8 to c32, and f64.
With explicit conversion, each C value corresponds to a list of BQN values with the same bit representation. For example, you might use u64:u1 to represent a 64-bit number as 64 bits (little-endian or least significant first), or u64:c8 to represent it as 8 characters. Similarly, a pointer can be turned into plain bits and back with *:u1. The : also applies to compound values; another case is an argument such as *i64:i32, which will be cast from a BQN list of 32-bit ints to a C list of 64-bit ints that's half as long (with an error if the length wasn't even). And & can be used instead of * to get mutated values out, converting back to i32 on the way. Other compound cases have some complications and aren't supported in CBQN currently.
Either the type as a whole, or any member of a struct, can have a conversion specification like :i32 at the end. The type after the colon uses the same format as C numeric types, with the quality c allowed for characters in addition to i, u, and f. Here CBQN supports the types it uses internally for arrays: u1 for booleans, i8 to i32 and c8 to c32, and f64.
With explicit conversion, each C value corresponds to a list of BQN values with the same bit representation. For example, you might use u64:u1 to represent a 64-bit number as 64 bits (little-endian or least significant first), or u64:c8 to represent it as 8 characters. Similarly, a pointer can be turned into plain bits and back with *:u1. The : also applies to compound values; another case is an argument such as *i64:i32, which will be cast from a BQN list of 32-bit ints to a C list of 64-bit ints that's half as long (with an error if the length wasn't even). **:i32 works similarly, assuming 64-bit pointers. The initial * can be replaced with & to get mutated values out, converting back to i32 on the way. Other compound cases have some complications and aren't supported in CBQN currently.
This section covers how FFI arguments and results are structured in BQN, and collects the ways to tweak it.
-The normal case is that 𝕩 is a list of the arguments. You can pass in 𝕨 if you really want, but is has to be an empty list. No arguments have been specified as coming from 𝕨! You can control where a C argument comes from by sticking 𝕨 or 𝕩 to the front (𝕩 does nothing, it's already the default). So for example, arguments of "i32"‿"𝕨i32"‿"𝕩i32" mean the function has to be called like ⟨2⟩ Fn 3‿4. Then if a C argument is the only one included in its BQN argument, it can have a > at the beginning (either before or after the 𝕨/𝕩) meaning that the BQN argument should be that value directly instead of the 1-element list.
If there are no mutable arguments, the result is what it is. Unless it isn't: a result type of "" results in a result value of @.
Mutable arguments (those with &) all have to be returned as part of the result. If there are any of these, the result is a list consisting of the C result followed by each mutable argument, mutatis mutandis, in the order they appeared in the arguments. Again, the result type can be "" to leave it out, so that the result just includes mutable values. It can also be "&" if there's exactly one such value, which means it won't be returned as a list.
The normal case is that 𝕩 is a list of the arguments. You can pass in 𝕨 if you really want, but is has to be an empty list. No arguments have been specified as coming from 𝕨! You can control where a C argument comes from by sticking 𝕨 or 𝕩 to the front (𝕩 does nothing, it's already the default). So for example, arguments of "i32"‿"𝕨i32"‿"𝕩i32" mean the function has to be called like ⟨2⟩ Fn 1‿3. Then if a C argument is the only one included in its BQN argument, it can have a > at the beginning (either before or after the 𝕨/𝕩) meaning that the BQN argument should be that value directly instead of the 1-element list.
If there are no mutable arguments, the result is what it is. Unless it isn't: a void result type "" results in a result value of @.
Mutable arguments (those with &) all have to be returned as part of the result. If there are any of these, the result is a list consisting of the C result followed by each mutable argument, mutatis mutandis, in the order they appeared in the arguments. Again, a result type of "" assumes a void result and leaves it out, so that the result just includes mutable values. A void result can also be written "&" if there's exactly one such value, which means it won't be returned as a list.
In the table of examples below, 5, 1, 0.5, and 3 are used as values for i8, u1, f64, and i64 respectively, and a and b are possible list arguments with am and bm indicating modified versions of these.