B.1 Interfacing Aspects
An
interfacing aspect is a representation
aspect that is one of the aspects Import, Export, Link_Name, External_Name,
or Convention.
Specifying
the Import aspect to have the value True 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,
specifying
the Export aspect to have the value True 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 Import and Export aspects are intended primarily for objects and
subprograms, although implementations are allowed to support other entities.
The Link_Name and External_Name aspects are used to specify the link
name and external name, respectively, to be used to identify imported
or exported entities in the external environment.
The Convention aspect
is used to indicate that an Ada entity should use the conventions of
another language. It is intended primarily for types and “callback”
subprograms. For example, “
with Convention => Fortran”
on the declaration of an array type Matrix implies that Matrix should
be represented according to the conventions of the supported Fortran
implementation, namely column-major order.
A
pragma
Linker_Options is used to specify the system linker parameters necessary
when a given compilation unit is included in a partition.
Syntax
The form of a
pragma
Linker_Options is as follows:
This paragraph
was deleted.
Name Resolution Rules
The Import and Export aspects are of type Boolean.
The Link_Name and External_Name aspects are of type
String.
The expected type for the
string_expression
in pragma Linker_Options is String.
Legality Rules
The aspect Convention shall be
specified by a
convention_identifier
which 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.
The
convention of a callable entity is its
calling 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:
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),
Convention
L has been specified for T, and T is
eligible for convention
L; that is:
T is an enumeration type such that
all internal codes (whether assigned by default or explicitly) are within
an implementation-defined range that includes at least the range of values
0 .. 2**15–1;
T is an array type with either an
unconstrained or statically-constrained first subtype, and its component
type is L-compatible,
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,
T is an access-to-object type, its
designated type is L-compatible, and its designated subtype is
not an unconstrained array subtype,
T is an access-to-subprogram type,
and its designated profile's parameter and result types are all L-compatible.
T is derived from an L-compatible type,
T is an anonymous access type, and T is eligible
for convention L,
The implementation permits T as an L-compatible
type.
If the Convention aspect is specified for a type,
then the type shall either be compatible with or eligible for the specified
convention.
If convention L is specified for a type
T, for each component of T that has an anonymous access type, the convention
of the anonymous access type is L. If convention L is specified
for an object that has an anonymous access type, the convention of the
anonymous access type is L.
Notwithstanding any rule to the
contrary, a declaration with a True Import aspect shall not have a completion.
An entity
with a True Import aspect (or Export aspect) is said to be
imported
(respectively,
exported). An entity shall not be both imported
and exported.
The declaration of an imported object shall not include
an explicit initialization expression. Default initializations are not
performed.
The type of an imported or exported object shall
be compatible with the specified Convention aspect, if any.
For an imported or exported subprogram, the result
and parameter types shall each be compatible with the specified Convention
aspect, if any.
The
aspect_definition
(if any) used to directly specify an Import, Export, External_Name, or
Link_Name aspect shall be a static expression. The
string_expression
of a
pragma
Linker_Options shall be static. An External_Name or Link_Name aspect
shall be specified only for an entity that is either imported or exported.
Static Semantics
Paragraphs 28 and
29 were deleted.
The Convention aspect
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:
A True Import aspect indicates that the entity
is defined externally (that is, outside the Ada program). This aspect
is never inherited; if not directly specified, the Import aspect is False.
A True Export aspect indicates that the entity
is used externally. This aspect is never inherited; if not directly specified,
the Export aspect is False.
For an entity with a True Import or Export aspect,
an external name, link name, or both may also be specified.
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.
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.
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.
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.
Dynamic Semantics
Notwithstanding
what this document says elsewhere, the elaboration of a declaration with
a True Import aspect does not create the entity. Such an elaboration
has no other effect than to allow the defining name to denote the external
entity.
Erroneous Execution
It is the programmer's responsibility
to ensure that the use of interfacing aspects does not violate Ada semantics;
otherwise, program execution is erroneous. For example, passing an object
with mode
in to imported code that modifies it causes erroneous
execution. Similarly, calling an imported subprogram that is not pure
from a pure package causes erroneous execution.
Implementation Advice
If an implementation supports Export for 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.
Automatic elaboration of preelaborated packages should
be provided when specifying the Export aspect as True is supported.
For each supported convention L other than
Intrinsic, an implementation should support specifying the Import and
Export aspects for objects of L-compatible types and for subprograms,
and the Convention aspect for L-eligible types and for subprograms,
presuming the other language has corresponding features. Specifying the
Convention aspect should be supported for enumeration types whose internal
codes fall within the range 0 .. 2**15–1, but no recommendation
is made for other scalar types.
NOTE 1 Implementations can place
restrictions on interfacing aspects; for example, requiring each exported
entity to be declared at the library level.
NOTE 2 The Convention aspect in combination
with the Import aspect indicates 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, with Convention => Ada can be used to interface
to an assembly language routine that obeys the Ada compiler's calling
conventions.
NOTE 3 To obtain “call-back”
to an Ada subprogram from a foreign language environment, the Convention
aspect can be specified both for the access-to-subprogram type and the
specific subprogram(s) to which 'Access is applied.
Paragraphs 45 and
46 were deleted.
NOTE 4 Machine code insertions can
also be relevant for interfacing; see
13.8.
NOTE 5 If both External_Name and
Link_Name are specified for a given entity, then the External_Name is
ignored.
This paragraph was
deleted.
Examples
Example of interfacing
aspects:
package Fortran_Library is
function Sqrt (X : Float) return Float
with Import => True, Convention => Fortran;
type Matrix is array (Natural range <>, Natural range <>) of Float
with Convention => Fortran;
function Invert (M : Matrix) return Matrix
with Import => True, Convention => Fortran;
end Fortran_Library;
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
