### C calling convention format

Arrangement is `"result"‿"fn"‿"arg0"‿"arg1"‿...`, which the possibility of allowing a single-string space-separated format in the future, or a structured representation like `⟨32,'i'⟩` for any given type. A lone symbol `"fn"` can indicate BQN calling convention.

Type construction rules:
- Empty type is void, for results only
- Primitive types are `f32`, `u8`, etc.
- A pointer `*i8` corresponds to a BQN array
- A final `*` corresponds to an object-like pointer value
- An array `[5]i16` also corresponds to a BQN array (may have some problems with libffi if not part of a struct?)
- Structs are `{i8, *, [2]f32}` and correspond to BQN arrays

The BQN type to use can be indicated with a suffix such as `:c8` (`:` character TBD?), with allowed types `iufc` as in `•bit._cast`. It can be appear after the whole type, or any member of a struct, and applies to the final component of the type *and* one preceding `*` or `[n]` if present. This value then corresponds to the specified type if there's no `*` or `[n]`, and a list of it if there is. This is sort of incomplete, since `u64:c8` to convert a 64-bit int to/from a list of characters seems desirable.

Questions:
- How to indicate a BQN value? Something like `u64:a` where `a` ("any") is a special BQN-side type best communicates what's happening, and a shortcut `a` would be the more commonly used version.
- How to represent mutability? Changing `*i16` to `&i16` seems fine, but the function result must now include the changed data.

### USE CASES


* Calling an existing C library, or writing a “pure C” library that doesn’t relate to BQN at all.
* Writing a library to interface with BQN, which might have bidirectional inputs and outputs, or maintain references or mutable state.

### USER STORIES

* Graphics Programming
* Live Music Programming
* Socket Programming

### Model 2 - JNA-Like (C calling convention)

https://en.wikipedia.org/wiki/Java_Native_Access#Architecture

> The JNA library uses a small native library called foreign function interface library (libffi) to dynamically invoke native code. The JNA library uses native functions allowing code to load a library by name and retrieve a pointer to a function within that library, and uses libffi library to invoke it, all without static bindings, header files, or any compile phase. The developer uses a Java interface to describe functions and structures in the target native library.

> The following program loads the local C standard library implementation and uses it to call the printf function. 

```
import com.sun.jna.Library;
import com.sun.jna.Native;
import com.sun.jna.Platform;

/** Simple example of native library declaration and usage. */
public class HelloWorld {
    public interface CLibrary extends Library {
        CLibrary INSTANCE = (CLibrary) Native.loadLibrary(
            (Platform.isWindows() ? "msvcrt" : "c"), CLibrary.class);
        void printf(String format, Object... args);
    }

    public static void main(String[] args) {
        CLibrary.INSTANCE.printf("Hello, World\n");
        for (int i = 0; i < args.length; i++) {
            CLibrary.INSTANCE.printf("Argument %d: %s\n", i, args[i]);
        }
    }
}
```

### MODEL 1 - JNI-Like (BQN calling convention)

[CBQN HEADER FILE](https://dzaima.github.io/paste/#0jVfNbhs3EL7vUwzkQyVDiSHZEIS6LdAYNRCgcFA0SY8Wtcu1GFHkhuRKUYIAufYJes8z5F6gfRM/SWdIane1Wks9yOYuv/nml5zZM6FSWWb8B@uyjOfPFz8lZ41XQrn2q7nWkt4lbltwFIESQZOrewcvfrt7e50kFxfgNOCOUBwYKObEmkNeqtQJrYa7HY2/jXALv9A5uAWCtJR6I9QDWPGAgqXh9nsiJGrY6tLcsRXv@6cPg@sndjZDaCKYykBqloFwIBRtBb1Wr7hbkDIplhxmvYK5xYXTF6leFULy7CLHv8@t7sHjl6@/IsOdd@VWvTJ/LJjja26AGeG2j1/@7u1M6M0SDFdOgbm/TwtZWvol/IPjRkHvpgefkjOuMpEnyVqLDObv1X1ueLR9jTYnmS7nkgP4PadvJ1dQ7QJ6FLNha9n1IKE0XI4xDUHoZsHMaaE9TYaz7EBXprlV37md@NMqSfpA6THpxBu11hh7ysmuQBIvT8CUSTkKdHkjpXv74/39ZuqJn6@ZLDFVXkOq0QKsAAZogl0AV2thtFpx5WpSkgic1qRNbbRx87sz/RSdPAfrTHBxp8L6ClallM8w1SuB5cszePP6dvqMK1Kdkcw18Pclk3RCZkEL/OjpV2zJCUwaEDcksOSK1gNUhAaX0kWst9Hi2yqc@IB1Rx5TGrAqDdtCxhxLrPjIY4bmulRZ8I0F29mSQWF0VqaOjqBdsIIP4d@//vn2@OfXPVnD1LISrQvXS8T3aLLHn8O8zAP/Bk9HrDhPwAZ4CPnKUhYQVAe3EOmyRQOFtjGLwScpgUtO2bJk7IzNkAbjSGG3BU9FLjDGSJtzU1voy3L6szGhrM9JAdXtlAwNlrbAowmi98GjSeVWC3w5PgDTiegEv2yZUVnRCW6ZUVnRCW6ZUVnRBcYjvgcOd8ATZryav9sDhwVUYJ@fFJF4xvT8HU@drbNKNY3a@vGWyZrHifb8dVFdIqK9HeMVy4EKqC6xWKp1CKnYDwhCDE8QxLB2EoS4niCIoe4iiLE@RlCHv4vg5nQM6mruJDgdg7rCOwlOx6Cu@i6CWELHCOqqigTtQnjL0yoIeCv@j8SjRFvgeKI7BI4nti1wKpEHPpxMXFvDyUR1CRxNTFvgIBF7AlV/akg0umE9Enqp/nnVdG7VaBCud7wjGi36afz4AN9u7ZsFV0AjAM@GMLIOm96Db6v5DOc7bBZznOlQfLbvw4toT79pXDU/IL7tdBQYNwXGLQFvUCYMXn/Q/8iNxlmj2A5iH6aWByxNubWVx1yVK/iEDc3di@kw/B9N4uJyHBb55Cos0ghJd5B0BynVEj6TKb/I10jtbQ9L70CwiR7r5k0XNlM4dsstlJaHwTsOX9irOU7gIPIwaAQmw3ESV2HASbXBWaTQOMHi5Ezu@BkbcCTBtiFWRWjRjNioTTdoNrqUGaUFs8Tkhm1tZN55MkQNpcVAWrb7DiCVZCQyxfiGQGIAHT7LbdLoopXDL6dQ@9vonDVgNNkD7LplDbgc14BGh6wA1NcqQGOgqAA3TRsaQ0QNaNrQGBxqQNOGro@Kz/FL4j8#C)

https://en.wikipedia.org/wiki/Java_Native_Interface#Design

> In the JNI framework, native functions are implemented in separate .c or .cpp files. (C++ provides a slightly simpler interface with JNI.) When the JVM invokes the function, it passes a JNIEnv pointer, a jobject pointer, and any Java arguments declared by the Java method. For example, the following converts a Java string to a native string:

```
extern "C"
JNIEXPORT void JNICALL Java_ClassName_MethodName
  (JNIEnv *env, jobject obj, jstring javaString)
{
    const char *nativeString = env->GetStringUTFChars(javaString, 0);

    //Do something with the nativeString

    env->ReleaseStringUTFChars(javaString, nativeString);
}
```

```
"path/to/compiled/file.so" •LoadNativeFnOrWhatever arity‿"yourName"
# could be expanded to 
"path/to/compiled/file.so" •LoadNativeFnOrWhatever "V←V V"‿"yourName"

# where "V←V V" is the signature of the function
# initial version could support some very trivial signatures and nothing else

```

### PRIOR WORK

https://code.jsoftware.com/wiki/Guides/DLLs/Calling_DLLs

https://github.com/mlochbaum/JSound/blob/master/synth.c#L12

https://github.com/mlochbaum/JSound/blob/master/filter.ijs#L8-L21

https://github.com/mlochbaum/BQNoise/blob/master/wav.bqn

---

https://help.dyalog.com/18.0/Content/Language/System%20Functions/na.htm

---

http://www.chiark.greenend.org.uk/doc/libffi-dev/html/Using-libffi.html#Using-libffi

http://gensoft.pasteur.fr/docs/libffi/3.3/libffi.pdf

---

https://github.com/dzaima/BQNative

https://github.com/dzaima/BQN/tree/master/app

https://github.com/ktye/i/blob/master/%2B/k.h

https://pycopy.readthedocs.io/en/latest/library/ffi.html#encoding-and-passing-values-of-types

https://docs.julialang.org/en/v1/base/c/#C-Interface