SML# Document Version 4.1.0

19 Expressions 19.20 Builtin types and builtin primitives 19.22 Dynamic import expression:

\,\langle

\rangle\,

: _import

\,\langle

cfunty

\rangle\,

19.21 Static import expression: _import $\,\langle$ string $\rangle\,$ : $\,\langle$ cfunty $\rangle\,$

This expression allows you to use C functions as SML# functions. The meaning of each component is as follows:

•

$\,\langle$ string $\rangle\,$ : the name of the C function. This is the name that linker recognizes as an external symbol name.
•

$\,\langle$ cfunty $\rangle\,$ : the type of the C function. It must be of the following form.

C function type: $\,\langle$ cfunty $\rangle\,$
$\,\langle$ cfunty $\rangle\,$	::=	$($ $\,\langle$ cfunattr $\rangle\,$ $)?$ $\,\langle$ argTyList $\rangle\,$ -> $\,\langle$ retTyOpt $\rangle\,$
$\,\langle$ argTyList $\rangle\,$	::=	( $\,\langle$ argTy $\rangle\,$ , $\ldots$ , $\,\langle$ argTy $\rangle\,$ $($ , $\,\langle$ varArgs $\rangle\,$ $)?$ )	(multiple arguments)
	$\|$	$\,\langle$ argTy $\rangle\,$	(only one argument)
	$\|$	()	(no argument)
$\,\langle$ retTyOpt $\rangle\,$	::=	$\,\langle$ retTy $\rangle\,$
	$\|$	()	(void type in C)
callback function type: $\,\langle$ argfunty $\rangle\,$
$\,\langle$ argfunty $\rangle\,$	::=	$($ $\,\langle$ cfunattr $\rangle\,$ $)?$ $\,\langle$ retTylist $\rangle\,$ -> $\,\langle$ argTyOpt $\rangle\,$
$\,\langle$ retTyList $\rangle\,$	::=	( $\,\langle$ retTy $\rangle\,$ , $\ldots$ , $\,\langle$ retTy $\rangle\,$ $($ , $\,\langle$ varRets $\rangle\,$ $)?$ )	(multiple arguments)
	$\|$	$\,\langle$ retTy $\rangle\,$	(only one argument)
	$\|$	()	(no argument)
$\,\langle$ argTyOpt $\rangle\,$	::=	$\,\langle$ argTy $\rangle\,$
	$\|$	()	(void type in C)
interoperable type: $\,\langle$ interoperableTy $\rangle\,$
$\,\langle$ interoperableTy $\rangle\,$	::=	$($ $\,\langle$ tySeq $\rangle\,$ $)?$ $\,\langle$ longTycon $\rangle\,$	(interoperable types only. See below for details)
argument type from SML# to C: $\,\langle$ argTy $\rangle\,$
$\,\langle$ argTy $\rangle\,$	::=	$\,\langle$ argTy $\rangle\,$ * $\cdots$ * $\,\langle$ argTy $\rangle\,$	(types of pointers to a structure)
	$\|$	{ $\,\langle$ argTyRow $\rangle\,$ }	(types of pointers to a structure)
	$\|$	$\,\langle$ tyvar $\rangle\,$	(boxed kind only)
	$\|$	$\,\langle$ interoperableTy $\rangle\,$
	$\|$	$\,\langle$ argfunty $\rangle\,$	(callback function argument types)
$\,\langle$ argTyRow $\rangle\,$	::=	$\,\langle$ lab $\rangle\,$ : $\,\langle$ argTy $\rangle\,$ $($ , $\,\langle$ argTyRow $\rangle\,$ $)?$	( $\,\langle$ lab $\rangle\,$ must begin with $\,\langle$ decimal $\rangle\,$ )
return type from C to SML#: $\,\langle$ retTy $\rangle\,$
$\,\langle$ retTy $\rangle\,$	::=	$\,\langle$ interoperableTy $\rangle\,$
	$\|$	$\,\langle$ tyvar $\rangle\,$	(boxed kind only)
variable-length argument type specification: $\,\langle$ varArgs $\rangle\,$ and $\,\langle$ varRets $\rangle\,$
$\,\langle$ varArgs $\rangle\,$	::=	... ( $\,\langle$ argTy $\rangle\,$ , $\ldots$ , $\,\langle$ argTy $\rangle\,$ )
$\,\langle$ varRets $\rangle\,$	::=	... ( $\,\langle$ retTy $\rangle\,$ , $\ldots$ , $\,\langle$ retTy $\rangle\,$ )
C function attributes: $\,\langle$ cfunattr $\rangle\,$
$\,\langle$ cfunattr $\rangle\,$	::=	__attribute__(( $\,\langle$ attr $\rangle\,$ , $\ldots$ , $\,\langle$ attr $\rangle\,$ ))
$\,\langle$ att $\rangle\,$	::=	cdecl $\|$ stdcall $\|$ fastcc $\|$ pure $\|$ fast

$\,\langle$ cfunty $\rangle\,$ indicates the type of the C function in SML#’s type names and type notation. $\,\langle$ interoperableTy $\rangle\,$ , the type names for C functions, must satisfy both of the following:

1.
$\,\langle$ interoperableTy $\rangle\,$ は以下のいずれかでなければならない．
- •
  
  Interoperable atomic types: int, int8, int16, int64, word, word8, word16, word64, real, real32, char, or string.
- •
  
  The types of C pointers: codeptr, $\,\langle$ interoperableTy $\rangle\,$ ptr, or unit ptr.
- •
  
  The types of C pointers: $\,\langle$ tyvar $\rangle\,$ ptr (ただし $\,\langle$ tyvar $\rangle\,$ must be of either boxed or unboxed kind).
- •
  
  The types of size: $\,\langle$ ty $\rangle\,$ size.
- •
  
  Array types: $\,\langle$ interoperableTy $\rangle\,$ array, $\,\langle$ interoperableTy $\rangle\,$ vector, or $\,\langle$ interoperableTy $\rangle\,$ ref.
- •
  
  Polymorphic array types: $\,\langle$ tyvar $\rangle\,$ array, $\,\langle$ tyvar $\rangle\,$ vector, or $\,\langle$ tyvar $\rangle\,$ ref (ただし $\,\langle$ tyvar $\rangle\,$ must be of either boxed or unboxed kind).
- •
  
  An alias of one of the above types defined by a type declaration. $($ $\,\langle$ tySeq $\rangle\,$ $)?$ $\,\langle$ longTycon $\rangle\,$ must be expanded to one of the above types. If an alias type occurs as an $\,\langle$ interoperableTy $\rangle\,$ in the context of $\,\langle$ argTy $\rangle\,$ , $($ $\,\langle$ tySeq $\rangle\,$ $)?$ $\,\langle$ longTycon $\rangle\,$ may be expanded to an tuple or record type that can be regarded as an $\,\langle$ argTy $\rangle\,$ .
2.

Neither string, array, vector, nor ref may occur as the type of values that would be passed from C to SML# or be overwritten by a C function. In other words, these types must not occur as
- •
  
  $\,\langle$ interoperableTy $\rangle\,$ in the context of $\,\langle$ retTy $\rangle\,$ , and
- •
  
  the type parameter of array, ref, and ptr type.

以上の条件を満たす $\,\langle$ interoperableTy $\rangle\,$ は，その型名から自然に類推されるCの型に相当する．対応を以下に示す．

$\,\langle$ interoperableTy $\rangle\,$	対応するCの型
int and its family	signed integer of the same size
word and its family	unsigned integer of the same size
real	double
real32	float
char	char
string	const char *
codeptr	pointer to a function
$\tau$ ptr	pointer to $\tau$
unit ptr	void * or pointer to an incomplete type
$\tau$ size	size_t
$\tau$ array	pointer to the beginning of an array of $\tau$
$\tau$ vector	pointer to the beginning of a vector of $\tau$
$\tau$ ref	pointer to an one-element array of $\tau$

Note that the size of int and word is always 32 bits. In almost of all modern operating systems, SML#’s int is identical to C’s int, whereas they are not identical in some systems whose int is not 32 bits.

$\,\langle$ argTy ${}_{1}$ $\rangle\,$ * $\cdots$ * $\,\langle$ argTy ${}_{n}$ $\rangle\,$ and { $\,\langle$ lab ${}_{1}$ $\rangle\,$ : $\,\langle$ argTy ${}_{1}$ $\rangle\,$ , $\cdots$ , $\,\langle$ lab ${}_{n}$ $\rangle\,$ : $\,\langle$ argTy ${}_{n}$ $\rangle\,$ } of $\,\langle$ argTy $\rangle\,$ corresponds to the type of pointers to a const structure whose members are of type $\,\langle$ argTy ${}_{1}$ $\rangle\,$ , $\cdots$ , $\,\langle$ argTy ${}_{n}$ $\rangle\,$ in the order of $\,\langle$ decimal $\rangle\,$ of labels. If all $\mbox{$\,\langle$}{\it argTy}\mbox{$\rangle\,$}_{i}$ are identical, it also corresponds to a pointer to the beginning of an const array of $n$ elements of $\mbox{$\,\langle$}{\it argTy}\mbox{$\rangle\,$}_{i}$ .

If and only if a C function acts like a parametric polymorphic function from the perspective of SML# programs, it is allowed to use type variables as a C function’s argument or return type. For example, an identical function in C

    void *id(void *x) { return x; }

is allowed to be imported like this:

    val ’a#boxed id = _import "id" : ’a -> ’a

Another example is printf function that prints an arbitrary pointer value.

    val ’a#boxed printPtr = _import "printf" : (string,...(’a)) -> int

The following C function attributes are available:

cdecl: The C function follows the standard calling convention of C functions on the target platform. This is the default if no calling convention is specified through function attributes.
stdcall: The C function follows stdcall calling convention on Windows platforms.
fastcc: The C function follows fastcc calling convention provided by LLVM.
pure: The C function is pure in the sense of SML#. In other words, C functions of this attribute does not perform any memory update and I/O, and its return value is decided only from the list of arguments. This attribute affects the optimization of the SML# compiler.
fast: The C function returns very quickly. It neither execute SML# code through callbacks nor pause the thread execution. The SML# compiler generates efficient invocation code for such functions. Note that, if a C function of this attribute either consumes much time or pause a thread execution, garbage collection would be suspended and consequently all threads would be suspended.

The type of this expression is the SML# function type corresponding to the type specified in $\,\langle$ cfunty $\rangle\,$ . The correspondence is defined as follows.

C function type	SML# function type
( $\,\langle$ argTy $\rangle\,$ ${}_{1}$ , $\ldots$ , $\,\langle$ argTy $\rangle\,$ ${}_{n}$ $($ $\,\langle$ varArgs $\rangle\,$ $)?$ ) -> $\,\langle$ retTy $\rangle\,$	$\,\langle$ argTy $\rangle\,$ ${}_{1}$ * $\cdots$ * $\,\langle$ argTy $\rangle\,$ ${}_{n}$ $($ * $\,\langle$ varArgs $\rangle\,$ $)?$ -> $\,\langle$ retTy $\rangle\,$

() in the argument or return type appear as unit in the SML# type. $\,\langle$ interoperableTy $\rangle\,$ , $\,\langle$ tyvar $\rangle\,$ , and $\,\langle$ * $\rangle\,$ appear in the SML# type without modification. $\,\langle$ argfunty $\rangle\,$ is interpreted similarly.

The value of this expression is the SML# function that calls the C function specified in $\,\langle$ string $\rangle\,$ . As long as the C function type specification is correct, this function can be used similarly to ordinary SML# functions.

19.21 Static import expression: _import ⟨string⟩ : ⟨cfunty⟩

19.21 Static import expression: _import $\,\langle$ string $\rangle\,$ : $\,\langle$ cfunty $\rangle\,$