Pragma Eliminate

Syntax:

     pragma Eliminate (
         [Unit_Name =>] IDENTIFIER |
                        SELECTED_COMPONENT);
     
     pragma Eliminate (
         [Unit_Name       =>]  IDENTIFIER |
                               SELECTED_COMPONENT,
         [Entity          =>]  IDENTIFIER |
                               SELECTED_COMPONENT |
                               STRING_LITERAL
         [,OVERLOADING_RESOLUTION]);
     
     OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
                                SOURCE_LOCATION
     
     PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
                                           FUNCTION_PROFILE
     
     PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
     
     FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
                           Result_Type => result_SUBTYPE_NAME]
     
     PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME})
     SUBTYPE_NAME    ::= STRING_VALUE
     
     SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
     SOURCE_TRACE    ::= STRING_VALUE
     
     STRING_VALUE ::= STRING_LITERAL {& STRING_LITERAL}

This pragma indicates that the given entity is not used outside the compilation unit it is defined in. The entity must be an explicitly declared subprogram; this includes generic subprogram instances and subprograms declared in generic package instances.

If the entity to be eliminated is a library level subprogram, then the first form of pragma Eliminate is used with only a single argument. In this form, the Unit_Name argument specifies the name of the library level unit to be eliminated.

In all other cases, both Unit_Name and Entity arguments are required. If item is an entity of a library package, then the first argument specifies the unit name, and the second argument specifies the particular entity. If the second argument is in string form, it must correspond to the internal manner in which GNAT stores entity names (see compilation unit Namet in the compiler sources for details).

The remaining parameters (OVERLOADING_RESOLUTION) are optionally used to distinguish between overloaded subprograms. If a pragma does not contain the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded subprograms denoted by the first two parameters.

Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram to be eliminated in a manner similar to that used for the extended Import and Export pragmas, except that the subtype names are always given as strings. At the moment, this form of distinguishing overloaded subprograms is implemented only partially, so we do not recommend using it for practical subprogram elimination.

Note that in case of a parameterless procedure its profile is represented as Parameter_Types => ("")

Alternatively, the Source_Location parameter is used to specify which overloaded alternative is to be eliminated by pointing to the location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the source text. The string literal (or concatenation of string literals) given as SOURCE_TRACE must have the following format:

     SOURCE_TRACE ::= SOURCE_LOCATION{LBRACKET SOURCE_LOCATION RBRACKET}
     
     LBRACKET ::= [
     RBRACKET ::= ]
     
     SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
     FILE_NAME       ::= STRING_LITERAL
     LINE_NUMBER     ::= DIGIT {DIGIT}

SOURCE_TRACE should be the short name of the source file (with no directory information), and LINE_NUMBER is supposed to point to the line where the defining name of the subprogram is located.

For the subprograms that are not a part of generic instantiations, only one SOURCE_LOCATION is used. If a subprogram is declared in a package instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the second one denotes the declaration of the corresponding subprogram in the generic package. This approach is recursively used to create SOURCE_LOCATIONs in case of nested instantiations.

The effect of the pragma is to allow the compiler to eliminate the code or data associated with the named entity. Any reference to an eliminated entity outside the compilation unit it is defined in, causes a compile time or link time error.

The intention of pragma Eliminate is to allow a program to be compiled in a system independent manner, with unused entities eliminated, without the requirement of modifying the source text. Normally the required set of Eliminate pragmas is constructed automatically using the gnatelim tool. Elimination of unused entities local to a compilation unit is automatic, without requiring the use of pragma Eliminate.

Note that the reason this pragma takes string literals where names might be expected is that a pragma Eliminate can appear in a context where the relevant names are not visible.

Note that any change in the source files that includes removing, splitting of adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION parameter illegal.

It is legal to use pragma Eliminate where the referenced entity is a dispatching operation, but it is not clear what this would mean, since in general the call does not know which entity is actually being called. Consequently, a pragma Eliminate for a dispatching operation is ignored.