B.1 Interfacing Pragmas
1
A pragma Import is used
to import an entity defined in a foreign language into an Ada program,
thus allowing a foreign-language subprogram to be called from Ada, or
a foreign-language variable to be accessed from Ada. In contrast, a pragma
Export is used to export an Ada entity to a foreign language, thus allowing
an Ada subprogram to be called from a foreign language, or an Ada object
to be accessed from a foreign language. The pragmas
Import and Export are intended primarily for objects and subprograms,
although implementations are allowed to support other entities.
2
A pragma Convention is
used to specify that an Ada entity should use the conventions of another
language. It is intended primarily for types and “callback”
subprograms. For example, “pragma Convention(Fortran, Matrix);”
implies that Matrix should be represented according to the conventions
of the supported Fortran implementation, namely column-major order.
3
A pragma Linker_Options
is used to specify the system linker parameters needed when a given compilation
unit is included in a partition.
Syntax
4
{interfacing
pragma [distributed]} {interfacing
pragma (Import) [partial]} {pragma,
interfacing (Import) [partial]} {interfacing
pragma (Export) [partial]} {pragma,
interfacing (Export) [partial]} {interfacing
pragma (Convention) [partial]} {pragma,
interfacing (Convention) [partial]} {pragma,
interfacing (Linker_Options) [partial]} An
interfacing pragma is a representation
pragma
that is one of the
pragmas Import, Export,
or Convention. Their forms, together with that of the related
pragma
Linker_Options, are as follows:
5
pragma Import(
[Convention =>]
convention_identifier,
[Entity =>]
local_name
[, [External_Name =>]
string_expression]
[, [Link_Name =>]
string_expression]);
6
pragma Export(
[Convention =>]
convention_identifier,
[Entity =>]
local_name
[, [External_Name =>]
string_expression]
[, [Link_Name =>]
string_expression]);
7
pragma Convention([Convention
=>]
convention_identifier,[Entity
=>]
local_name);
8
pragma Linker_Options(
string_expression);
9
A pragma Linker_Options
is allowed only at the place of a declarative_item.
9.1/1
{
8652/0058}
{
AI95-00036-01}
For pragmas Import and
Export, the argument for Link_Name shall not be given without the pragma_argument_identifier
unless the argument for External_Name is given. Name Resolution Rules
10
{expected type (link
name) [partial]} The expected type for
a
string_expression
in an interfacing pragma or in pragma Linker_Options is String.
10.a
Ramification: There is no language-defined
support for external or link names of type Wide_String, or of other string
types. Implementations may, of course, have additional pragmas for that
purpose. Note that allowing both String and Wide_String in the same pragma
would cause ambiguities.
Legality Rules
11
{convention}
The
convention_identifier
of an interfacing pragma shall be the name of a
convention. The
convention names are implementation defined, except for certain language-defined
ones, such as Ada and Intrinsic, as explained in
6.3.1,
“
Conformance Rules”. [Additional
convention names generally represent the calling conventions of foreign
languages, language implementations, or specific run-time models.]
{calling
convention} The convention of a callable
entity is its
calling convention.
11.a
Implementation defined: Implementation-defined
convention names.
11.b
Discussion: We considered representing
the convention names using an enumeration type declared in System. Then,
convention_identifier would be changed
to convention_name, and we would make
its expected type be the enumeration type. We didn't do this because
it seems to introduce extra complexity, and because the list of available
languages is better represented as the list of children of package Interfaces
— a more open-ended sort of list.
12
{compatible
(a type, with a convention)} If
L
is a
convention_identifier for a language,
then a type T is said to be
compatible with convention L, (alternatively,
is said to be an
L-compatible type) if any of the following conditions
are met:
13
- T is declared in a language interface
package corresponding to L and is defined to be L-compatible
(see B.3, B.3.1,
B.3.2, B.4, B.5),
14
- {eligible
(a type, for a convention)} Convention
L has been specified for T in a pragma
Convention, and T is eligible for convention L; that is:
15
- T is an array type with either
an unconstrained or statically-constrained first subtype, and its component
type is L-compatible,
16
- T is a record type that has
no discriminants and that only has components with statically-constrained
subtypes, and each component type is L-compatible,
17
- T is an access-to-object type,
and its designated type is L-compatible,
18
- T is an access-to-subprogram
type, and its designated profile's parameter and result types are all
L-compatible.
19
- T is derived from an L-compatible
type,
20
- The implementation permits T as an
L-compatible type.
20.a
Discussion: For example, an implementation
might permit Integer as a C-compatible type, though the C type to which
it corresponds might be different in different environments.
21
If pragma Convention applies
to a type, then the type shall either be compatible with or eligible
for the convention specified in the pragma.
21.a
Ramification: If a type is derived from
an L-compatible type, the derived type is by default L-compatible,
but it is also permitted to specify pragma Convention for the derived
type.
21.b
It is permitted to specify pragma Convention
for an incomplete type, but in the complete declaration each component
must be L-compatible.
21.c
If each component of a record type is L-compatible,
then the record type itself is only L-compatible if it has a pragma
Convention.
22
A
pragma Import shall
be the completion of a declaration.
{notwithstanding}
Notwithstanding any rule to the contrary, a
pragma
Import may serve as the completion of any kind of (explicit) declaration
if supported by an implementation for that kind of declaration. If a
completion is a
pragma Import, then it shall
appear in the same
declarative_part,
package_specification,
task_definition or
protected_definition
as the declaration. For a library unit, it shall appear in the same
compilation,
before any subsequent
compilation_units other
than
pragmas. If the
local_name
denotes more than one entity, then the
pragma
Import is the completion of all of them.
22.a
Discussion: For declarations of deferred
constants and subprograms, we mention pragma Import explicitly as a possible
completion. For other declarations that require completions, we ignore
the possibility of pragma Import. Nevertheless, if an implementation
chooses to allow a pragma Import to complete
the declaration of a task, protected type, incomplete type, private type,
etc., it may do so, and the normal completion is then not allowed for
that declaration.
23
{imported entity}
{exported entity}
An entity specified as the Entity argument to a
pragma
Import (or
pragma Export) is said to be
imported
(respectively,
exported).
24
The declaration of an imported object shall not include
an explicit initialization expression. [Default initializations are not
performed.]
24.a
Proof: This follows from the “Notwithstanding
...” wording in the Dynamics Semantics paragraphs below.
25
The type of an imported or exported object shall
be compatible with the convention specified in the corresponding pragma.
25.a
Ramification: This implies, for example,
that importing an Integer object might be illegal, whereas importing
an object of type Interfaces.C.int would be permitted.
26
For an imported or exported subprogram, the result
and parameter types shall each be compatible with the convention specified
in the corresponding pragma.
27
The external name and link name string_expressions
of a pragma Import or Export, and the string_expression
of a pragma Linker_Options, shall be static.
Static Semantics
28
{representation pragma
(Import) [partial]} {pragma,
representation (Import) [partial]} {representation
pragma (Export) [partial]} {pragma,
representation (Export) [partial]} {representation
pragma (Convention) [partial]} {pragma,
representation (Convention) [partial]} {aspect
of representation (convention, calling convention) [partial]}
{convention (aspect
of representation)} Import, Export, and
Convention
pragmas are representation pragmas
that specify the
convention aspect of representation.
{aspect
of representation (imported) [partial]} {imported
(aspect of representation)} {aspect
of representation (exported) [partial]} {exported
(aspect of representation)} In addition,
Import and Export
pragmas specify the
imported
and
exported aspects of representation, respectively.
29
{program unit pragma
(Import) [partial]} {pragma,
program unit (Import) [partial]} {program
unit pragma (Export) [partial]} {pragma,
program unit (Export) [partial]} {program
unit pragma (Convention) [partial]} {pragma,
program unit (Convention) [partial]} An
interfacing pragma is a program unit pragma when applied to a program
unit (see
10.1.5).
30
An interfacing pragma
defines the convention of the entity denoted by the local_name.
The convention represents the calling convention or representation convention
of the entity. For an access-to-subprogram type, it represents the calling
convention of designated subprograms. In addition:
31
- A pragma
Import specifies that the entity is defined externally (that is, outside
the Ada program).
32
- A pragma
Export specifies that the entity is used externally.
33
- A pragma
Import or Export optionally specifies an entity's external name, link
name, or both.
34
{external name}
An
external name is a string value for the
name used by a foreign language program either for an entity that an
Ada program imports, or for referring to an entity that an Ada program
exports.
35
{link name}
A
link name is a string value for the name
of an exported or imported entity, based on the conventions of the foreign
language's compiler in interfacing with the system's linker tool.
36
The meaning of link names is implementation defined.
If neither a link name nor the Address attribute of an imported or exported
entity is specified, then a link name is chosen in an implementation-defined
manner, based on the external name if one is specified.
36.a
Implementation defined: The meaning of
link names.
36.b
Ramification: For example, an implementation
might always prepend "_", and then pass it to the system linker.
36.c
Implementation defined: The manner of
choosing link names when neither the link name nor the address of an
imported or exported entity is specified.
36.d
Ramification: Normally, this will be
the entity's defining name, or some simple transformation thereof.
37
Pragma Linker_Options has the effect of passing its
string argument as a parameter to the system linker (if one exists),
if the immediately enclosing compilation unit is included in the partition
being linked. The interpretation of the string argument, and the way
in which the string arguments from multiple Linker_Options pragmas are
combined, is implementation defined.
37.a
Implementation defined: The effect of
pragma Linker_Options.
Dynamic Semantics
38
{elaboration (declaration
named by a pragma Import) [partial]} {notwithstanding}
Notwithstanding what this International Standard
says elsewhere, the elaboration of a declaration denoted by the
local_name
of a
pragma Import does not create the entity.
Such an elaboration has no other effect than to allow the defining name
to denote the external entity.
38.a
Ramification: This implies that default
initializations are skipped. (Explicit initializations are illegal.)
For example, an imported access object is not initialized to null.
38.b
Note that the local_name
in a pragma Import might denote more than
one declaration; in that case, the entity of all of those declarations
will be the external entity.
38.c
Discussion: This “notwithstanding”
wording is better than saying “unless named by a pragma
Import” on every definition of elaboration. It says we recognize
the contradiction, and this rule takes precedence.
Erroneous Execution
38.1/2
{
AI95-00320-01}
{erroneous execution
(cause) [partial]} It is the programmer's
responsibility to ensure that the use of interfacing pragmas does not
violate Ada semantics; otherwise, program execution is erroneous.
Implementation Advice
39
If an implementation supports pragma Export to a
given language, then it should also allow the main subprogram to be written
in that language. It should support some mechanism for invoking the elaboration
of the Ada library units included in the system, and for invoking the
finalization of the environment task. On typical systems, the recommended
mechanism is to provide two subprograms whose link names are "adainit"
and "adafinal". Adainit should contain the elaboration code
for library units. Adafinal should contain the finalization code. These
subprograms should have no effect the second and subsequent time they
are called.
{adainit}
{adafinal}
{Elaboration (of
library units for a foreign language main subprogram)} {Finalization
(of environment task for a foreign language main subprogram)}
39.a.1/2
Implementation Advice:
If pragma
Export is supported for a language, the main program should be able to
be written in that language. Subprograms named "adainit" and
"adafinal" should be provided for elaboration and finalization
of the environment task.
39.a
Ramification: For example, if the main
subprogram is written in C, it can call adainit before the first call
to an Ada subprogram, and adafinal after the last.
40
Automatic elaboration of preelaborated packages should
be provided when pragma Export is supported.
40.a.1/2
Implementation Advice:
Automatic elaboration of preelaborated
packages should be provided when pragma Export
is supported.
41
For each supported convention L other than
Intrinsic, an implementation should support Import and Export pragmas
for objects of L-compatible types and for subprograms, and pragma
Convention for L-eligible types and for subprograms, presuming
the other language has corresponding features. Pragma
Convention need not be supported for scalar types.
41.a.1/2
Implementation Advice:
For each supported convention L
other than Intrinsic, pragmas Import and Export
should be supported for objects of L-compatible types and for
subprograms, and pragma Convention should
be supported for L-eligible types and for subprograms.
41.a
Reason: Pragma Convention is not necessary
for scalar types, since the language interface packages declare scalar
types corresponding to those provided by the respective foreign languages.
41.b/2
Implementation Note: {
AI95-00114-01}
If an implementation supports interfacing to
the
C++
entities not supported by B.3,
it should do so via the convention identifier C_Plus_Plus (in additional
to any C++-implementation-specific ones).
41.c/2
Reason: {
AI95-00114-01}
The reason for giving the advice about C++ is to encourage uniformity
among implementations, given that the name of the language is not syntactically
legal as an
identifier.
We place this advice in the AARM, rather than the RM95 proper, because
(as of this writing) C++ is not an international standard, and we don't
want to refer to a such a language from an international standard.
42
1 Implementations may place restrictions
on interfacing pragmas; for example, requiring each exported entity to
be declared at the library level.
42.a
Proof: Arbitrary restrictions are allowed
by
13.1.
42.b
Ramification: Such a restriction might
be to disallow them altogether. Alternatively, the implementation might
allow them only for certain kinds of entities, or only for certain conventions.
43
2 A pragma Import
specifies the conventions for accessing external entities. It is possible
that the actual entity is written in assembly language, but reflects
the conventions of a particular language. For example, pragma
Import(Ada, ...) can be used to interface to an assembly language routine
that obeys the Ada compiler's calling conventions.
44
3 To obtain “call-back” to
an Ada subprogram from a foreign language environment, pragma
Convention should be specified both for the access-to-subprogram type
and the specific subprogram(s) to which 'Access is applied.
45
4 It is illegal to specify more than one
of Import, Export, or Convention for a given entity.
46
5 The local_name
in an interfacing pragma can denote more than one entity in the case
of overloading. Such a pragma applies to all
of the denoted entities.
47
47.a
Ramification: The Intrinsic convention
(see
6.3.1) implies that the entity is somehow
“built in” to the implementation. Thus, it generally does
not make sense for users to specify Intrinsic in a
pragma
Import. The intention is that only implementations will specify Intrinsic
in a
pragma Import. The language also defines
certain subprograms to be Intrinsic.
47.b
Discussion: There are many imaginable
interfacing pragmas that don't make any sense. For example, setting the
Convention of a protected procedure to Ada is probably wrong. Rather
than enumerating all such cases, however, we leave it up to implementations
to decide what is sensible.
48
7 If both External_Name and Link_Name are
specified for an Import or Export pragma, then the External_Name is ignored.
49/2
This paragraph was
deleted.8 {
AI95-00320-01}
An interfacing pragma might result in an effect
that violates Ada semantics.
Examples
50
Example of interfacing
pragmas:
51
package Fortran_Library is
function Sqrt (X : Float) return Float;
function Exp (X : Float) return Float;
private
pragma Import(Fortran, Sqrt);
pragma Import(Fortran, Exp);
end Fortran_Library;
Extensions to Ada 83
51.a
{
extensions to Ada 83}
Interfacing
pragmas are new to Ada 95. Pragma Import replaces Ada 83's pragma Interface.
Existing implementations can continue to support pragma Interface for
upward compatibility.
Wording Changes from Ada 95
51.b/2
{
8652/0058}
{
AI95-00036-01}
Corrigendum: Clarified that pragmas
Import and Export work like a subprogram call; parameters cannot be omitted
unless named notation is used. (Reordering is still not permitted, however.)51.c/2
{
AI95-00320-01}
Added wording to say all bets are off if foreign
code doesn't follow the semantics promised by the Ada specifications.
Sponsored by Ada-Europe