Node: Implementation Advice, Next: Implementation Defined Characteristics, Previous: Implementation Defined Attributes, Up: Top
The main text of the Ada 95 Reference Manual describes the required behavior of all Ada 95 compilers, and the GNAT compiler conforms to these requirements.
In addition, there are sections throughout the Ada 95 reference manual headed by the phrase "implementation advice". These sections are not normative, i.e. they do not specify requirements that all compilers must follow. Rather they provide advice on generally desirable behavior. You may wonder why they are not requirements. The most typical answer is that they describe behavior that seems generally desirable, but cannot be provided on all systems, or which may be undesirable on some systems.
As far as practical, GNAT follows the implementation advice sections in the Ada 95 Reference Manual. This chapter contains a table giving the reference manual section number, paragraph number and several keywords for each advice. Each entry consists of the text of the advice followed by the GNAT interpretation of this advice. Most often, this simply says "followed", which means that GNAT follows the advice. However, in a number of cases, GNAT deliberately deviates from this advice, in which case the text describes what GNAT does and why.
If an implementation detects the use of an unsupported Specialized Needs
Annex feature at run time, it should raise Program_Error if
feasible.
|
If an implementation wishes to provide implementation-defined extensions to the functionality of a language-defined library unit, it should normally do so by adding children to the library unit. |
If an implementation detects a bounded error or erroneous
execution, it should raise Program_Error .
|
Normally, implementation-defined pragmas should have no semantic effect for error-free programs; that is, if the implementation-defined pragmas are removed from a working program, the program should still be legal, and should still have the same semantics. |
Abort_Defer
Ada_83
Assert
CPP_Class
CPP_Constructor
CPP_Virtual
CPP_Vtable
Debug
Interface_Name
Machine_Attribute
Unimplemented_Unit
Unchecked_Union
In each of the above cases, it is essential to the purpose of the pragma
that this advice not be followed. For details see the separate section
on implementation defined pragmas.
Normally, an implementation should not define pragmas that can make an illegal program legal, except as follows: |
A pragma used to complete a declaration, such as a pragma Import ;
|
A pragma used to configure the environment by adding, removing, or
replacing library_items .
|
If an implementation supports a mode with alternative interpretations
for Character and Wide_Character , the set of graphic
characters of Character should nevertheless remain a proper
subset of the set of graphic characters of Wide_Character . Any
character set "localizations" should be reflected in the results of
the subprograms defined in the language-defined package
Characters.Handling (see A.3) available in such a mode. In a mode with
an alternative interpretation of Character , the implementation should
also support a corresponding change in what is a legal
identifier_letter .
|
An implementation should support Long_Integer in addition to
Integer if the target machine supports 32-bit (or longer)
arithmetic. No other named integer subtypes are recommended for package
Standard . Instead, appropriate named integer subtypes should be
provided in the library package Interfaces (see B.2).
|
Long_Integer
is supported. Other standard integer types are supported
so this advice is not fully followed. These types
are supported for convenient interface to C, and so that all hardware
types of the machine are easily available.
An implementation for a two's complement machine should support
modular types with a binary modulus up to System.Max_Int*2+2 . An
implementation should support a non-binary modules up to Integer'Last .
|
For the evaluation of a call on S'Pos for an enumeration
subtype, if the value of the operand does not correspond to the internal
code for any enumeration literal of its type (perhaps due to an
un-initialized variable), then the implementation should raise
Program_Error . This is particularly important for enumeration
types with noncontiguous internal codes specified by an
enumeration_representation_clause.
|
An implementation should support Long_Float in addition to
Float if the target machine supports 11 or more digits of
precision. No other named floating point subtypes are recommended for
package Standard . Instead, appropriate named floating point subtypes
should be provided in the library package Interfaces (see B.2).
|
Short_Float
and Long_Long_Float
are also provided. The
former provides improved compatibility with other implementations
supporting this type. The latter corresponds to the highest precision
floating-point type supported by the hardware. On most machines, this
will be the same as Long_Float
, but on some machines, it will
correspond to the IEEE extended form. The notable case is all ia32
(x86) implementations, where Long_Long_Float
corresponds to
the 80-bit extended precision format supported in hardware on this
processor. Note that the 128-bit format on SPARC is not supported,
since this is a software rather than a hardware format.
An implementation should normally represent multidimensional arrays in
row-major order, consistent with the notation used for multidimensional
array aggregates (see 4.3.3). However, if a pragma Convention
(Fortran , ...) applies to a multidimensional array type, then
column-major order should be used instead (see B.5, "Interfacing with
Fortran").
|
Whenever possible in an implementation, the value of Duration'Small
should be no greater than 100 microseconds.
|
Duration'Small
= 10**(-9)).
The time base for delay_relative_statements should be monotonic;
it need not be the same time base as used for Calendar.Clock .
|
In an implementation, a type declared in a pre-elaborated package should have the same representation in every elaboration of a given version of the package, whether the elaborations occur in distinct executions of the same program, or in executions of distinct programs or partitions that include the given version. |
Exception_Message by default and Exception_Information
should produce information useful for
debugging. Exception_Message should be short, about one
line. Exception_Information can be long. Exception_Message
should not include the
Exception_Name . Exception_Information should include both
the Exception_Name and the Exception_Message .
|
Exception_Message
, the compiler generates one containing the location
of the raise statement. This location has the form "file:line", where
file is the short file name (without path information) and line is the line
number in the file. Note that in the case of the Zero Cost Exception
mechanism, these messages become redundant with the Exception_Information that
contains a full backtrace of the calling sequence, so they are disabled.
To disable explicitly the generation of the source location message, use the
Pragma Discard_Names
.
The implementation should minimize the code executed for checks that have been suppressed. |
The recommended level of support for all representation items is qualified as follows: |
An implementation need not support representation items containing non-static expressions, except that an implementation should support a representation item for a given entity if each non-static expression in the representation item is a name that statically denotes a constant declared before the entity. |
X : typ; for X'Address use To_address (16#2000#);
will be rejected, since the To_Address expression is non-static. Instead write:
X_Address : constant Address : = To_Address ((16#2000#); X : typ; for X'Address use X_Address;
An implementation need not support a specification for the Size
for a given composite subtype, nor the size or storage place for an
object (including a component) of a given composite subtype, unless the
constraints on the subtype and its composite subcomponents (if any) are
all static constraints.
|
An aliased component, or a component whose type is by-reference, should always be allocated at an addressable location. |
If a type is packed, then the implementation should try to minimize storage allocated to objects of the type, possibly at the expense of speed of accessing components, subject to reasonable complexity in addressing calculations. |
The recommended level of support pragma Pack is:
For a packed record type, the components should be packed as tightly as
possible subject to the Sizes of the component subtypes, and subject to
any |
An implementation should support Address clauses for imported subprograms. |
For an array X, X'Address should point at the first
component of the array, and not at the array bounds.
|
The recommended level of support for the Address attribute is:
|
An implementation should support Address clauses for imported
subprograms.
|
Objects (including subcomponents) that are aliased or of a by-reference type should be allocated on storage element boundaries. |
If the Address of an object is specified, or it is imported or exported,
then the implementation should not perform optimizations based on
assumptions of no aliases.
|
The recommended level of support for the Alignment attribute for
subtypes is:
An implementation should support specified Alignments that are factors and multiples of the number of storage elements per word, subject to the following: |
An implementation need not support specified Alignment s for
combinations of Size s and Alignment s that cannot be easily
loaded and stored by available machine instructions.
|
An implementation need not support specified Alignment s that are
greater than the maximum Alignment the implementation ever returns by
default.
|
The recommended level of support for the Alignment attribute for
objects is:
Same as above, for subtypes, but in addition: |
For stand-alone library-level objects of statically constrained
subtypes, the implementation should support all Alignment s
supported by the target linker. For example, page alignment is likely to
be supported for such objects, but not for subtypes.
|
The recommended level of support for the Size attribute of
objects is:
A |
If the Size of a subtype is specified, and allows for efficient
independent addressability (see 9.10) on the target architecture, then
the Size of the following objects of the subtype should equal the
Size of the subtype:
Aliased objects (including components). |
Size clause on a composite subtype should not affect the
internal layout of components.
|
The recommended level of support for the Size attribute of subtypes is:
|
The Size (if not specified) of a static discrete or fixed point
subtype should be the number of bits needed to represent each value
belonging to the subtype using an unbiased representation, leaving space
for a sign bit only if the subtype contains negative values. If such a
subtype is a first subtype, then an implementation should support a
specified Size for it that reflects this representation.
|
For a subtype implemented with levels of indirection, the Size
should include the size of the pointers, but not the size of what they
point at.
|
The recommended level of support for the Component_Size
attribute is:
|
An implementation need not support specified Component_Sizes that are
less than the Size of the component subtype.
|
An implementation should support specified Component_Size s that
are factors and multiples of the word size. For such
Component_Size s, the array should contain no gaps between
components. For other Component_Size s (if supported), the array
should contain no gaps between components when packing is also
specified; the implementation should forbid this combination in cases
where it cannot support a no-gaps representation.
|
The recommended level of support for enumeration representation clauses
is:
An implementation need not support enumeration representation clauses
for boolean types, but should at minimum support the internal codes in
the range |
The recommended level of support for
record_representation_clauses is:
An implementation should support storage places that can be extracted with a load, mask, shift sequence of machine code, and set with a load, shift, mask, store sequence, given the available machine instructions and run-time model. |
A storage place should be supported if its size is equal to the
Size of the component subtype, and it starts and ends on a
boundary that obeys the Alignment of the component subtype.
|
If the default bit ordering applies to the declaration of a given type,
then for a component whose subtype's Size is less than the word
size, any storage place that does not cross an aligned word boundary
should be supported.
|
An implementation may reserve a storage place for the tag field of a tagged type, and disallow other components from overlapping that place. |
An implementation need not support a component_clause for a
component of an extension part if the storage place is not after the
storage places of all components of the parent type, whether or not
those storage places had been specified.
|
If a component is represented using some form of pointer (such as an offset) to the actual data of the component, and this data is contiguous with the rest of the object, then the storage place attributes should reflect the place of the actual data, not the pointer. If a component is allocated discontinuously from the rest of the object, then a warning should be generated upon reference to one of its storage place attributes. |
The recommended level of support for the non-default bit ordering is: |
If Word_Size = Storage_Unit , then the implementation
should support the non-default bit ordering in addition to the default
bit ordering.
|
Address should be of a private type.
|
Operations in System and its children should reflect the target
environment semantics as closely as is reasonable. For example, on most
machines, it makes sense for address arithmetic to "wrap around."
Operations that do not make sense should raise Program_Error .
|
Program_Error
, since all operations make sense.
The Size of an array object should not include its bounds; hence,
the bounds should not be part of the converted data.
|
The implementation should not generate unnecessary run-time checks to ensure that the representation of S is a representation of the target type. It should take advantage of the permission to return by reference when possible. Restrictions on unchecked conversions should be avoided unless required by the target environment. |
The recommended level of support for unchecked conversions is: |
Unchecked conversions should be supported and should be reversible in the cases where this clause defines the result. To enable meaningful use of unchecked conversion, a contiguous representation should be used for elementary subtypes, for statically constrained array subtypes whose component subtype is one of the subtypes described in this paragraph, and for record subtypes without discriminants whose component subtypes are described in this paragraph. |
An implementation should document any cases in which it dynamically allocates heap storage for a purpose other than the evaluation of an allocator. |
A default (implementation-provided) storage pool for an access-to- constant type should not have overhead to support de-allocation of individual objects. |
A storage pool for an anonymous access type should be created at the point of an allocator for the type, and be reclaimed when the designated object becomes inaccessible. |
For a standard storage pool, Free should actually reclaim the
storage.
|
If a stream element is the same size as a storage element, then the
normal in-memory representation should be used by Read and
Write for scalar objects. Otherwise, Read and Write
should use the smallest number of stream elements needed to represent
all values in the base range of the scalar type.
|
If an implementation provides additional named predefined integer types,
then the names should end with Integer as in
Long_Integer . If an implementation provides additional named
predefined floating point types, then the names should end with
Float as in Long_Float .
|
Ada.Characters.Handling
If an implementation provides a localized definition of Character
or Wide_Character , then the effects of the subprograms in
Characters.Handling should reflect the localizations. See also
3.5.2.
|
Bounded string objects should not be implemented by implicit pointers and dynamic allocation. |
Any storage associated with an object of type Generator should be
reclaimed on exit from the scope of the object.
|
If the generator period is sufficiently long in relation to the number
of distinct initiator values, then each possible value of
Initiator passed to Reset should initiate a sequence of
random numbers that does not, in a practical sense, overlap the sequence
initiated by any other value. If this is not possible, then the mapping
between initiator values and generator states should be a rapidly
varying function of the initiator value.
|
Get_Immediate
The Get_Immediate procedures should be implemented with
unbuffered input. For a device such as a keyboard, input should be
available if a key has already been typed, whereas for a disk
file, input should always be available except at end of file. For a file
associated with a keyboard-like device, any line-editing features of the
underlying operating system should be disabled during the execution of
Get_Immediate .
|
Export
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.
|
Automatic elaboration of pre-elaborated packages should be provided when pragma Export is supported. |
adainit
must be called to elaborate pre-elaborated
packages.
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.
|
Interfaces
For each implementation-defined convention identifier, there should be a
child package of package Interfaces with the corresponding name. This
package should contain any declarations that would be useful for
interfacing to the language (implementation) represented by the
convention. Any declarations useful for interfacing to any language on
the given hardware architecture should be provided directly in
Interfaces .
|
Interfaces.CPP
, used
for interfacing to C++.
An implementation supporting an interface to C, COBOL, or Fortran should provide the corresponding package or packages described in the following clauses. |
An implementation should support the following interface correspondences between Ada and C. |
An Ada procedure corresponds to a void-returning C function. |
An Ada function corresponds to a non-void C function. |
An Ada in scalar parameter is passed as a scalar argument to a C
function.
|
An Ada in parameter of an access-to-object type with designated
type T is passed as a t* argument to a C function,
where t is the C type corresponding to the Ada type T.
|
An Ada access T parameter, or an Ada out or in out
parameter of an elementary type T, is passed as a t*
argument to a C function, where t is the C type corresponding to
the Ada type T. In the case of an elementary out or
in out parameter, a pointer to a temporary copy is used to
preserve by-copy semantics.
|
An Ada parameter of a record type T, of any mode, is passed as a
t* argument to a C function, where t is the C
structure corresponding to the Ada type T.
|
An Ada parameter of an array type with component type T, of any
mode, is passed as a t* argument to a C function, where
t is the C type corresponding to the Ada type T.
|
An Ada parameter of an access-to-subprogram type is passed as a pointer to a C function whose prototype corresponds to the designated subprogram's specification. |
An Ada implementation should support the following interface correspondences between Ada and COBOL. |
An Ada access T parameter is passed as a "BY REFERENCE" data item of the COBOL type corresponding to T. |
An Ada in scalar parameter is passed as a "BY CONTENT" data item of the corresponding COBOL type. |
Any other Ada parameter is passed as a "BY REFERENCE" data item of the COBOL type corresponding to the Ada parameter type; for scalars, a local copy is used if necessary to ensure by-copy semantics. |
An Ada implementation should support the following interface correspondences between Ada and Fortran: |
An Ada procedure corresponds to a Fortran subroutine. |
An Ada function corresponds to a Fortran function. |
An Ada parameter of an elementary, array, or record type T is passed as a T argument to a Fortran procedure, where T is the Fortran type corresponding to the Ada type T, and where the INTENT attribute of the corresponding dummy argument matches the Ada formal parameter mode; the Fortran implementation's parameter passing conventions are used. For elementary types, a local copy is used if necessary to ensure by-copy semantics. |
An Ada parameter of an access-to-subprogram type is passed as a reference to a Fortran procedure whose interface corresponds to the designated subprogram's specification. |
The machine code or intrinsic support should allow access to all operations normally available to assembly language programmers for the target environment, including privileged instructions, if any. |
The interfacing pragmas (see Annex B) should support interface to
assembler; the default assembler should be associated with the
convention identifier Assembler .
|
If an entity is exported to assembly language, then the implementation should allocate it at an addressable location, and should ensure that it is retained by the linking process, even if not otherwise referenced from the Ada code. The implementation should assume that any call to a machine code or assembler subprogram is allowed to read or update every object that is specified as exported. |
The implementation should ensure that little or no overhead is associated with calling intrinsic and machine-code subprograms. |
It is recommended that intrinsic subprograms be provided for convenient access to any machine operations that provide special capabilities or efficiency and that are not otherwise available through the language constructs. |
Atomic read-modify-write operations - e.g., test and set, compare and swap, decrement and test, enqueue/dequeue. |
Standard numeric functions - e.g., sin, log. |
String manipulation operations - e.g., translate and test. |
Vector operations - e.g., compare vector against thresholds. |
Direct operations on I/O ports. |
If the Ceiling_Locking policy is not in effect, the
implementation should provide means for the application to specify which
interrupts are to be blocked during protected actions, if the underlying
system allows for a finer-grain control of interrupt blocking.
|
Whenever possible, the implementation should allow interrupt handlers to be called directly by the hardware. |
Whenever practical, violations of any implementation-defined restrictions should be detected before run time. |
Interrupts
If implementation-defined forms of interrupt handler procedures are
supported, such as protected procedures with parameters, then for each
such form of a handler, a type analogous to Parameterless_Handler
should be specified in a child package of Interrupts , with the
same operations as in the predefined package Interrupts.
|
It is recommended that pre-elaborated packages be implemented in such a way that there should be little or no code executed at run time for the elaboration of entities not already covered by the Implementation Requirements. |
Discard_Names
If the pragma applies to an entity, then the implementation should reduce the amount of storage used for storing names associated with that entity. |
Some implementations are targeted to domains in which memory use at run time must be completely deterministic. For such implementations, it is recommended that the storage for task attributes will be pre-allocated statically and not from the heap. This can be accomplished by either placing restrictions on the number and the size of the task's attributes, or by using the pre-allocated storage for the first N attribute objects, and the heap for the others. In the latter case, N should be documented. |
The implementation should use names that end with _Locking for
locking policies defined by the implementation.
|
Inheritance_Locking
) follows this suggestion.
Names that end with _Queuing should be used
for all implementation-defined queuing policies.
|
Even though the abort_statement is included in the list of
potentially blocking operations (see 9.5.1), it is recommended that this
statement be implemented in a way that never requires the task executing
the abort_statement to block.
|
On a multi-processor, the delay associated with aborting a task on another processor should be bounded; the implementation should use periodic polling, if necessary, to achieve this. |
When feasible, the implementation should take advantage of the specified restrictions to produce a more efficient implementation. |
Ravenscar
and pragma
Restricted_Run_Time
for more details.
When appropriate, implementations should provide configuration
mechanisms to change the value of Tick .
|
It is recommended that Calendar.Clock and Real_Time.Clock
be implemented as transformations of the same time base.
|
It is recommended that the best time base which exists in
the underlying system be available to the application through
Clock . Best may mean highest accuracy or largest range.
|
Whenever possible, the PCS on the called partition should allow for multiple tasks to call the RPC-receiver with different messages and should allow them to block until the corresponding subprogram body returns. |
The Write operation on a stream of type Params_Stream_Type
should raise Storage_Error if it runs out of space trying to
write the Item into the stream.
|
If COBOL (respectively, C) is widely supported in the target
environment, implementations supporting the Information Systems Annex
should provide the child package Interfaces.COBOL (respectively,
Interfaces.C ) specified in Annex B and should support a
convention_identifier of COBOL (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language.
|
Packed decimal should be used as the internal representation for objects of subtype S when S'Machine_Radix = 10. |
If Fortran (respectively, C) is widely supported in the target
environment, implementations supporting the Numerics Annex
should provide the child package Interfaces.Fortran (respectively,
Interfaces.C ) specified in Annex B and should support a
convention_identifier of Fortran (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language.
|
Because the usual mathematical meaning of multiplication of a complex operand and a real operand is that of the scaling of both components of the former by the latter, an implementation should not perform this operation by first promoting the real operand to complex type and then performing a full complex multiplication. In systems that, in the future, support an Ada binding to IEC 559:1989, the latter technique will not generate the required result when one of the components of the complex operand is infinite. (Explicit multiplication of the infinite component by the zero component obtained during promotion yields a NaN that propagates into the final result.) Analogous advice applies in the case of multiplication of a complex operand and a pure-imaginary operand, and in the case of division of a complex operand by a real or pure-imaginary operand. |
Similarly, because the usual mathematical meaning of addition of a
complex operand and a real operand is that the imaginary operand remains
unchanged, an implementation should not perform this operation by first
promoting the real operand to complex type and then performing a full
complex addition. In implementations in which the Signed_Zeros
attribute of the component type is True (and which therefore
conform to IEC 559:1989 in regard to the handling of the sign of zero in
predefined arithmetic operations), the latter technique will not
generate the required result when the imaginary component of the complex
operand is a negatively signed zero. (Explicit addition of the negative
zero to the zero obtained during promotion yields a positive zero.)
Analogous advice applies in the case of addition of a complex operand
and a pure-imaginary operand, and in the case of subtraction of a
complex operand and a real or pure-imaginary operand.
|
Implementations in which Real'Signed_Zeros is True should
attempt to provide a rational treatment of the signs of zero results and
result components. As one example, the result of the Argument
function should have the sign of the imaginary component of the
parameter X when the point represented by that parameter lies on
the positive real axis; as another, the sign of the imaginary component
of the Compose_From_Polar function should be the same as
(respectively, the opposite of) that of the Argument parameter when that
parameter has a value of zero and the Modulus parameter has a
nonnegative (respectively, negative) value.
|
Implementations in which Complex_Types.Real'Signed_Zeros is
True should attempt to provide a rational treatment of the signs
of zero results and result components. For example, many of the complex
elementary functions have components that are odd functions of one of
the parameter components; in these cases, the result component should
have the sign of the parameter component at the origin. Other complex
elementary functions have zero components whose sign is opposite that of
a parameter component at the origin, or is always positive or always
negative.
|
The versions of the forward trigonometric functions without a
Cycle parameter should not be implemented by calling the
corresponding version with a Cycle parameter of
2.0*Numerics.Pi , since this will not provide the required
accuracy in some portions of the domain. For the same reason, the
version of Log without a Base parameter should not be
implemented by calling the corresponding version with a Base
parameter of Numerics.e .
|
The version of the Compose_From_Polar function without a
Cycle parameter should not be implemented by calling the
corresponding version with a Cycle parameter of
2.0*Numerics.Pi , since this will not provide the required
accuracy in some portions of the domain.
|