B.1 Interfacing AspectsInterfacing Pragmas
0.1/3
{
AI05-0229-1}
An interfacing aspect is a representation
aspect that is one of the aspects Import, Export, Link_Name, External_Name,
or Convention.1/3
{
AI05-0229-1}
Specifying
aspect A pragma
Import
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
aspect a pragma
Export
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
pragmas
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.1.a/3
Aspect Description
for Import: Entity
is imported from another language.
1.b/3
Aspect Description
for Export: Entity
is exported to another language.
1.c/3
Aspect Description
for External_Name: Name
used to identify an imported or exported entity.
1.d/3
Aspect Description
for Link_Name: Linker
symbol used to identify an imported or exported entity.
2/3
{
AI05-0229-1}
The A pragma
Convention
aspect
is used to
indicate specify
that an Ada entity should use the conventions of another language. It
is intended primarily for types and “callback” subprograms.
For example, “
with pragma
Convention
=> (Fortran
,
Matrix);”
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.
2.a/3
Aspect Description
for Convention: Calling
convention or other convention used for interfacing to other languages.
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/3
{
AI05-0229-1}
The form of a
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
is,
are as follows:
5/3
6/3
7/3
8
9
9.1/3
Name Resolution Rules
9.2/3
{
AI05-0229-1}
The Import and Export aspects are of type Boolean.10/3
{
AI05-0229-1}
The
Link_Name and External_Name aspects are of expected
type
for a string_expression
in an interfacing pragma or in pragma Linker_Options is String.
10.a/3
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
aspects pragmas
for that purpose. Note that allowing both String and Wide_String in the
same
aspect_definition pragma
would cause ambiguities.
10.1/3
Legality Rules
11/3
{
AI05-0229-1}
The
aspect Convention shall
be specified by a convention_identifier
which 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.]
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
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/3
{
AI05-0229-1}
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/3
{
AI05-0002-1}
T is an access-to-object type,
and its designated
type is
L-compatible,
and its designated
subtype is not an unconstrained array subtype,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/3
{
AI05-0229-1}
If
the pragma
Convention
aspect is specified for applies
to a type, then the type shall either be compatible with or eligible
for the convention specified in the pragma.
21.a/3
Ramification: {
AI05-0229-1}
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
the pragma
Convention
aspect for the derived type.
21.b/3
{
AI05-0229-1}
It is permitted to specify
the pragma
Convention
aspect for an incomplete type,
but in the complete declaration each component must be
L-compatible.
21.c/3
{
AI05-0229-1}
If each component of a record type is
L-compatible, then the record
type itself is only
L-compatible if it has
a
specified a pragma Convention.
22/3
22.a/3
Discussion: {
AI05-0229-1}
For declarations of deferred constants and subprograms, we
explicitly
mention
that no completion is allowed when
aspect pragma Import
is
True explicitly as a possible completion.
For other declarations that require completions, we ignore the possibility
of
the aspect pragma
Import
being True. Nevertheless, if an implementation
chooses to allow
specifying aspect a
pragma
Import to
be True for 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/3
{
AI05-0229-1}
An entity
with
a True specified as the Entity argument
to a pragma
Import
aspect (or
pragma
Export
aspect) is said to be
imported
(respectively,
exported).
An entity shall
not be both imported and 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/3
{
AI05-0229-1}
The type of an imported or exported object shall be compatible with the
specified Convention aspect, if any 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/3
{
AI05-0229-1}
For an imported or exported subprogram, the result and parameter types
shall each be compatible with the
specified Convention
aspect, if any convention specified in the
corresponding pragma.
27/3
{
AI05-0229-1}
The aspect_definition
(if any) used to directly specify an The
external name and link name string_expressions
of a pragma
Import
, or
Export,
External_Name, or Link_Name aspect shall
be a static expression. The and 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.
28/3
{
AI05-0229-1}
Import,
Export, and Convention pragmas
are representation pragmas that specify the convention aspect
of representation. In
addition, Import and Export pragmas
specify the imported and exported aspects of representation,
respectively.29/3
{
AI05-0229-1}
An
interfacing pragma is a program unit pragma when applied to a program
unit (see 10.1.5).30/3
{
AI05-0229-1}
An interfacing pragma defines the convention of
the entity denoted by the local_name.
The
Convention aspect 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/3
A
True pragma
Import
aspect indicates specifies
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.32/3
A
True pragma
Export
aspect indicates specifies
that the entity is used externally.
This aspect
is never inherited; if not directly specified, the Export aspect is False.33/3
For an entity with a True A
pragma
Import or Export
aspect, an optionally
specifies an entity's external name, link name, or both
may also be specified.
34
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
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/3
{
AI05-0229-1}
Notwithstanding
what this International Standard says elsewhere, the elaboration of a
declaration
with a True Import aspect 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/3
This paragraph
was deleted.{
AI05-0229-1}
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/3
Discussion: {
AI05-0229-1}
This “notwithstanding” wording is better than saying “unless
aspect named by a
pragma
Import
is True ” on every definition
of elaboration. It says we recognize the contradiction, and this rule
takes precedence.
Erroneous Execution
38.1/3
{
AI95-00320-01}
{
AI05-0229-1}
It is the programmer's responsibility
to ensure that the use of interfacing aspects pragmas does not violate Ada semantics; otherwise, program execution is erroneous.
Implementation Advice
39/3
{
AI05-0229-1}
If an implementation supports
pragma Export
for 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.
39.a.1/3
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/3
{
AI05-0229-1}
Automatic elaboration of preelaborated packages should be provided when
specifying pragma
Export
as True is supported.
40.a.1/3
Implementation Advice: Automatic
elaboration of preelaborated packages should be provided when specifying pragma Export as True is
supported.
41/3
{
AI05-0229-1}
For each supported convention
L other than Intrinsic, an implementation
should support
specifying the Import and
Export
aspects pragmas
for objects of
L-compatible types and for subprograms, and
the pragma
Convention
aspect for
L-eligible
types and for subprograms, presuming the other language has corresponding
features.
Specifying the Pragma
Convention
aspect need not be supported
for scalar types.
41.a.1/3
Implementation Advice: For
each supported convention L other than Intrinsic, specifying
the aspects pragmas Import and Export should be supported for objects of L-compatible
types and for subprograms, and aspect pragma Convention should be supported for L-eligible types and for subprograms.
41.a/3
Reason: {
AI05-0229-1}
Specifying aspect 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/3
1 {
AI05-0229-1}
Implementations may place restrictions on interfacing
aspects 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/3
2 {
AI05-0229-1}
The Convention aspect in combination with the A
pragma
Import
aspect indicates 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,
with
Convention => Ada pragma
Import(Ada, ...) can be used to interface to an assembly language
routine that obeys the Ada compiler's calling conventions.
44/3
3 {
AI05-0229-1}
To obtain “call-back” to an Ada subprogram from a foreign
language environment,
the pragma
Convention
aspect should 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.
45/3
4 {
AI05-0229-1}
It is illegal to specify more than one of Import,
Export, or Convention for a given entity.46/3
5 {
AI05-0229-1}
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/3
Ramification: {
AI05-0229-1}
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
along with specifying that the entity is imported in
a pragma Import.
The intention is that only implementations will specify Intrinsic
for
an imported entity in a pragma
Import. The language also defines certain subprograms to be Intrinsic.
47.b/3
Discussion: {
AI05-0229-1}
There are many imaginable interfacing
aspects 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/3
7 {
AI05-0229-1}
If both External_Name and Link_Name are specified for
a
given entity 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/3
{
AI05-0229-1}
package Fortran_Library
is
function Sqrt (X : Float)
return Float
with Import => True, Convention => Fortran;
function Exp (X : Float)
return Float
with Import => True, Convention => Fortran;
private
pragma Import(Fortran, Sqrt);
pragma Import(Fortran, Exp);
end Fortran_Library;
Extensions to Ada 83
51.a
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.
Incompatibilities With Ada 2005
51.d/3
{
AI05-0002-1}
Correction: Access types
that designate unconstrained arrays are no longer defined to be L-compatible.
Such access-to-arrays require bounds information, which is likely to
be incompatible with a foreign language. The change will allow (but not
require) compilers to reject bad uses, which probably will not work anyway.
Note that implementations can still support any type that it wants as
L-compatible; such uses will not be portable, however. As such,
there should be little existing code that will be impacted (compilers
probably already rejected cases that could not be translated, whether
or not the language allowed doing so formally). Extensions to Ada 2005
51.e/3
{
AI05-0229-1}
Aspects Convention, Import,
Export, Link_Name, and External_Name are new; pragmas
Convention, Import, and Export are now obsolescent.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
