Interoperability¶
Chapel’s interoperability features support cooperation between Chapel and other languages. They provide the ability to create software systems that incorporate both Chapel and non-Chapel components. Thus, they support the reuse of existing software components while leveraging the unique features of the Chapel language.
Interoperability can be broken down in terms of the exchange of types, variables and procedures, and whether these are imported or exported. An overview of procedure importing and exporting is provided in Interoperability Overview. Details on sharing types, variables and procedures are supplied in Shared Language Elements.
Note
Future:
At present, the backend language for Chapel is C, which makes it relatively easy to call C libraries from Chapel and vice versa. To support a variety of platforms without requiring recompilation, it may be desirable to move to an intermediate-language model.
In that case, each supported platform must minimally support that virtual machine. However, in addition to increased portability, a virtual machine model may expose elements of the underlying machine’s programming model (hardware task queues, automated garbage collection, etc.) that are not easily rendered in C. In addition, the virtual machine model can support run-time task migration.
The remainder of this chapter documents Chapel support of interoperability through the existing C-language backend.
Interoperability Overview¶
The following two subsections provide an overview of calling externally-defined (C) routines in Chapel, and setting up Chapel routines so they can be called from external (C) code.
Calling External Functions¶
To use an external function in a Chapel program, it is necessary to
inform the Chapel compiler of that routine’s signature through an
external function declaration. This permits Chapel to bind calls to that
function signature during function resolution. The user must also supply
a definition for the referenced function by naming a C source file, an
object file or an object library on the chpl
command line.
An external procedure declaration has the following syntax:
external-procedure-declaration-statement:
'extern' external-name[OPT] 'proc' identifier argument-list return-intent[OPT] return-type[OPT] ;
Chapel code will call the external function using the parameter types
supplied in the extern
declaration. Therefore, in general, the type
of each argument in the supplied argument-list
must be the Chapel
equivalent of the corresponding external type.
The return value of the function can be used by Chapel only if its type
is declared using the optional return-type
specifier. If it is
omitted, Chapel assumes that no value is returned, or equivalently that
the function returns void
.
It is possible to use the external-name
syntax to create an
extern
function that presents a different name to Chapel code than
the name of the function actually used when linking. The
external-name
expression must evaluate to a param
string
.
For example, the code below declares a function callable in Chapel as
c_atoi
but that will actually link with the C atoi
function.
extern "atoi" proc c_atoi(arg:c_ptrConst(c_char)):c_int;
At present, external iterators are not supported.
Note
Future:
The overloading of function names is also not supported directly in the compiler. However, one can use the
external-name
syntax to supply a name to be used by the linker. In this way, function overloading can be implemented “by hand”. This syntax also supports calling external C++ routines: Theexternal-name
to use is the mangled function name generated by the external compilation environment [1].
Note
Future:
Dynamic dispatch (polymorphism) is also unsupported in this version. But this is not ruled out in future versions. Since Chapel already supports type-based procedure declaration and resolution, it is a small step to translate a type-relative extern method declaration into a virtual method table entry. The mangled name of the correct external function must be supplied for each polymorphic type available. However, most likely the generation of
.chpl
header files from C and C++ libraries can be fully automated.
There are three ways to supply to the Chapel compiler the definition of
an external function: as a C source file (.c
or .h
), as an
object file and as an object library. It is platform-dependent whether
static libraries (archives), dynamic libraries or both are supported.
See the chpl
man page for more information on how these file types
are handled.
Calling Chapel Functions¶
To call a Chapel procedure from external code, it is necessary to expose
the corresponding function symbol to the linker. This is done by adding
the export
linkage specifier to the function definition. The
export
specifier ensures that the corresponding procedure will be
resolved, even if it is not called within the Chapel program or library
being compiled.
An exported procedure declaration has the following syntax:
exported-procedure-declaration-statement:
'export' external-name[OPT] 'proc' identifier argument-list return-intent[OPT] return-type[OPT]
function-body
external-name:
expression
The rest of the procedure declaration is the same as for a non-exported function. An exported procedure can be called from within Chapel as well. Currently, iterators cannot be exported.
As with the extern-name
for extern
proc
, if this syntax
element is provided, then it must be a param
string
and will be
used to determine the name of the function to use when linking. For
example, the code below declares a function callable in C as
chapel_addone
but it is callable from Chapel code as addone
:
export "chapel_addone" proc addone(arg:c_int):c_int {
return arg+1;
}
Note
Future.
Currently, exported functions cannot have generic,
param
or type arguments. This is because such functions actually represent a family of functions, specific versions of which are instantiated as need during function resolution.Instantiating all possible versions of a template function is not practical in general. However, if explicit instantiation were supported in Chapel, an explicit instantiation with the export linkage specifier would clearly indicate that the matching template function was to be instantiated with the given
param
values and argument types.