HCoop / hcoop / debian / mlton.git / blame
| Commit | Line | Data |
|---|---|---|
| 7f918cf1 CE |
1 | ForeignFunctionInterfaceTypes |
| 2 | ============================= | |
| 3 | ||
| 4 | MLton's <:ForeignFunctionInterface:> only allows values of certain SML | |
| 5 | types to be passed between SML and C. The following types are | |
| 6 | allowed: `bool`, `char`, `int`, `real`, `word`. All of the different | |
| 7 | sizes of (fixed-sized) integers, reals, and words are supported as | |
| 8 | well: `Int8.int`, `Int16.int`, `Int32.int`, `Int64.int`, | |
| 9 | `Real32.real`, `Real64.real`, `Word8.word`, `Word16.word`, | |
| 10 | `Word32.word`, `Word64.word`. There is a special type, | |
| 11 | `MLton.Pointer.t`, for passing C pointers -- see <:MLtonPointer:> for | |
| 12 | details. | |
| 13 | ||
| 14 | Arrays, refs, and vectors of the above types are also allowed. | |
| 15 | Because in MLton monomorphic arrays and vectors are exactly the same | |
| 16 | as their polymorphic counterpart, these are also allowed. Hence, | |
| 17 | `string`, `char vector`, and `CharVector.vector` are also allowed. | |
| 18 | Strings are not null terminated, unless you manually do so from the | |
| 19 | SML side. | |
| 20 | ||
| 21 | Unfortunately, passing tuples or datatypes is not allowed because that | |
| 22 | would interfere with representation optimizations. | |
| 23 | ||
| 24 | The C header file that `-export-header` generates includes | |
| 25 | ++typedef++s for the C types corresponding to the SML types. Here is | |
| 26 | the mapping between SML types and C types. | |
| 27 | ||
| 28 | [options="header"] | |
| 29 | |==== | |
| 30 | | SML type | C typedef | C type | Note | |
| 31 | | `array` | `Pointer` | `unsigned char *` | | |
| 32 | | `bool` | `Bool` | `int32_t` | | |
| 33 | | `char` | `Char8` | `uint8_t` | | |
| 34 | | `Int8.int` | `Int8` | `int8_t` | | |
| 35 | | `Int16.int` | `Int16` | `int16_t` | | |
| 36 | | `Int32.int` | `Int32` | `int32_t` | | |
| 37 | | `Int64.int` | `Int64` | `int64_t` | | |
| 38 | | `int` | `Int32` | `int32_t` | <:#Default:(default)> | |
| 39 | | `MLton.Pointer.t` | `Pointer` | `unsigned char *` | | |
| 40 | | `Real32.real` | `Real32` | `float` | | |
| 41 | | `Real64.real` | `Real64` | `double` | | |
| 42 | | `real` | `Real64` | `double` | <:#Default:(default)> | |
| 43 | | `ref` | `Pointer` | `unsigned char *` | | |
| 44 | | `string` | `Pointer` | `unsigned char *` | <:#ReadOnly:(read only)> | |
| 45 | | `vector` | `Pointer` | `unsigned char *` | <:#ReadOnly:(read only)> | |
| 46 | | `Word8.word` | `Word8` | `uint8_t` | | |
| 47 | | `Word16.word` | `Word16` | `uint16_t` | | |
| 48 | | `Word32.word` | `Word32` | `uint32_t` | | |
| 49 | | `Word64.word` | `Word64` | `uint64_t` | | |
| 50 | | `word` | `Word32` | `uint32_t` | <:#Default:(default)> | |
| 51 | |==== | |
| 52 | ||
| 53 | <!Anchor(Default)>Note (default): The default `int`, `real`, and | |
| 54 | `word` types may be set by the ++-default-type __type__++ | |
| 55 | <:CompileTimeOptions: compiler option>. The given C typedef and C | |
| 56 | types correspond to the default behavior. | |
| 57 | ||
| 58 | <!Anchor(ReadOnly)>Note (read only): Because MLton assumes that | |
| 59 | vectors and strings are read-only (and will perform optimizations | |
| 60 | that, for instance, cause them to share space), you must not modify | |
| 61 | the data pointed to by the `unsigned char *` in C code. | |
| 62 | ||
| 63 | Although the C type of an array, ref, or vector is always `Pointer`, | |
| 64 | in reality, the object has the natural C representation. Your C code | |
| 65 | should cast to the appropriate C type if you want to keep the C | |
| 66 | compiler from complaining. | |
| 67 | ||
| 68 | When calling an <:CallingFromSMLToC: imported C function from SML> | |
| 69 | that returns an array, ref, or vector result or when calling an | |
| 70 | <:CallingFromCToSML: exported SML function from C> that takes an | |
| 71 | array, ref, or string argument, then the object must be an ML object | |
| 72 | allocated on the ML heap. (Although an array, ref, or vector object | |
| 73 | has the natural C representation, the object also has an additional | |
| 74 | header used by the SML runtime system.) | |
| 75 | ||
| 76 | In addition, there is an <:MLBasis:> file, `$(SML_LIB)/basis/c-types.mlb`, | |
| 77 | which provides structure aliases for various C types: | |
| 78 | ||
| 79 | |==== | |
| 80 | | C type | Structure | Signature | |
| 81 | | `char` | `C_Char` | `INTEGER` | |
| 82 | | `signed char` | `C_SChar` | `INTEGER` | |
| 83 | | `unsigned char` | `C_UChar` | `WORD` | |
| 84 | | `short` | `C_Short` | `INTEGER` | |
| 85 | | `signed short` | `C_SShort` | `INTEGER` | |
| 86 | | `unsigned short` | `C_UShort` | `WORD` | |
| 87 | | `int` | `C_Int` | `INTEGER` | |
| 88 | | `signed int` | `C_SInt` | `INTEGER` | |
| 89 | | `unsigned int` | `C_UInt` | `WORD` | |
| 90 | | `long` | `C_Long` | `INTEGER` | |
| 91 | | `signed long` | `C_SLong` | `INTEGER` | |
| 92 | | `unsigned long` | `C_ULong` | `WORD` | |
| 93 | | `long long` | `C_LongLong` | `INTEGER` | |
| 94 | | `signed long long` | `C_SLongLong` | `INTEGER` | |
| 95 | | `unsigned long long` | `C_ULongLong` | `WORD` | |
| 96 | | `float` | `C_Float` | `REAL` | |
| 97 | | `double` | `C_Double` | `REAL` | |
| 98 | | `size_t` | `C_Size` | `WORD` | |
| 99 | | `ptrdiff_t` | `C_Ptrdiff` | `INTEGER` | |
| 100 | | `intmax_t` | `C_Intmax` | `INTEGER` | |
| 101 | | `uintmax_t` | `C_UIntmax` | `WORD` | |
| 102 | | `intptr_t` | `C_Intptr` | `INTEGER` | |
| 103 | | `uintptr_t` | `C_UIntptr` | `WORD` | |
| 104 | | `void *` | `C_Pointer` | `WORD` | |
| 105 | |==== | |
| 106 | ||
| 107 | These aliases depend on the configuration of the C compiler for the | |
| 108 | target architecture, and are independent of the configuration of MLton | |
| 109 | (including the ++-default-type __type__++ | |
| 110 | <:CompileTimeOptions: compiler option>). |