Next: , Previous: , Up: Foreign language interface   [Contents]

14.4 Using foreign types from Mercury

Types defined in a foreign language can be accessed in Mercury using a declaration of the form

:- pragma foreign_type(Lang, MercuryTypeName, ForeignTypeDescriptor).

This defines MercuryTypeName as a synonym for type ForeignTypeDescriptor defined in the foreign language Lang. You must declare MercuryTypeName using a (possibly abstract) ‘:- type’ declaration as usual. The ‘pragma foreign_type’ must not have wider visibility than the type declaration (if the ‘pragma foreign_type’ declaration is in the interface, the ‘:- type’ declaration must be also).

ForeignTypeDescriptor defines how the Mercury type is mapped for a particular foreign language. Specific syntax is given in the language specific information below.

MercuryTypeName is treated as an abstract type at all times in Mercury code. However, if MercuryTypeName is one of the parameters of a foreign_proc for Lang, and the ‘pragma foreign_type’ declaration is visible to the foreign_proc, it will be passed to that foreign_proc as specified by ForeignTypeDescriptor.

Multiple foreign language definitions may be given for the same type — the appropriate definition will be used for the appropriate language (see the language specific information below for details). All definitions must have the same visibility. A Mercury definition, which must define a discriminated union type, may also be given. The constructors for the type will only be visible in Mercury clauses for predicates or functions with ‘pragma foreign_proc’ clauses for all of the languages for which there are ‘foreign_type’ declarations for the type.

You can also associate assertions about the properties of the foreign type with the ‘foreign_type’ declaration, using the following syntax:

:- pragma foreign_type(Lang, MercuryTypeName, ForeignTypeDescriptor, [ForeignTypeAssertion, ...]).

Currently, two kinds of assertions are supported. The ‘can_pass_as_mercury_type’ assertion states that on the C backends, values of the given type can be passed to and from Mercury code without boxing, via simple casts, which is faster. This requires the type to be either an integer type or a pointer type, and requires its size to be the same as or less than the size of Mercury word. Since deciding whether a C type satisfies this condition requires knowledge of the Mercury implementation, and violations are very likely to result in the generated executable silently doing the wrong thing, we do not recommend the use of assertions unless you are an implementor of the Mercury system. The ‘stable’ assertion is meaningful only in the presence of the ‘can_pass_as_mercury_type’ assertion. It states that either the C type is an integer type, or it is a pointer type pointing to memory that will never change. Together, these assertions are sufficient to allow tabling (see Tabled evaluation) and the ‘compare_representation’ primitive to work on values of such types.

As with discriminated union types, programmers can specify the unification and/or comparison predicates to use for values of the type using the following syntax (see User-defined equality and comparison):

:- pragma foreign_type(Lang, MercuryTypeName, ForeignTypeDescriptor)
        where equality is EqualityPred, comparison is ComparePred.

You can use Mercury foreign language interfacing declarations which specify language X to interface to types that are actually written in a different language Y provided that X and Y have compatible interface conventions. Support for this kind of compatibility is described in the language specific information below.

Next: , Previous: , Up: Foreign language interface   [Contents]