+2019-07-08 Hristian Kirtchev <kirtchev@adacore.com>
+
+ * doc/gnat_rm/implementation_defined_pragmas.rst:
+ Update the documentation of pragma Initialize_Scalars.
+ * gnat_rm.texi: Regenerate.
+
2019-07-08 Javier Miranda <miranda@adacore.com>
* exp_ch4.adb (Tagged_Membership): Fix regression silently
``As_Is`` provides the normal default behavior in which the casing is
taken from the string provided.
-This pragma may appear anywhere that a pragma is valid. In particular, it
+This pragma may appear anywhere that a pragma is valid. In particular, it
can be used as a configuration pragma in the :file:`gnat.adc` file, in which
case it applies to all subsequent compilations, or it can be used as a program
unit pragma, in which case it only applies to the current unit, or it can
.. code-block:: ada
- pragma Initialize_Scalars;
+ pragma Initialize_Scalars
+ [ ( TYPE_VALUE_PAIR {, TYPE_VALUE_PAIR} ) ];
+ TYPE_VALUE_PAIR ::=
+ SCALAR_TYPE => static_EXPRESSION
-This pragma is similar to ``Normalize_Scalars`` conceptually but has
-two important differences. First, there is no requirement for the pragma
-to be used uniformly in all units of a partition, in particular, it is fine
-to use this just for some or all of the application units of a partition,
-without needing to recompile the run-time library.
+ SCALAR_TYPE :=
+ Short_Float
+ | Float
+ | Long_Float
+ | Long_Long_Flat
+ | Signed_8
+ | Signed_16
+ | Signed_32
+ | Signed_64
+ | Unsigned_8
+ | Unsigned_16
+ | Unsigned_32
+ | Unsigned_64
-In the case where some units are compiled with the pragma, and some without,
-then a declaration of a variable where the type is defined in package
-Standard or is locally declared will always be subject to initialization,
-as will any declaration of a scalar variable. For composite variables,
-whether the variable is initialized may also depend on whether the package
-in which the type of the variable is declared is compiled with the pragma.
-The other important difference is that you can control the value used
-for initializing scalar objects. At bind time, you can select several
-options for initialization. You can
-initialize with invalid values (similar to Normalize_Scalars, though for
-Initialize_Scalars it is not always possible to determine the invalid
-values in complex cases like signed component fields with non-standard
-sizes). You can also initialize with high or
-low values, or with a specified bit pattern. See the GNAT
-User's Guide for binder options for specifying these cases.
+This pragma is similar to ``Normalize_Scalars`` conceptually but has two
+important differences.
-This means that you can compile a program, and then without having to
-recompile the program, you can run it with different values being used
-for initializing otherwise uninitialized values, to test if your program
-behavior depends on the choice. Of course the behavior should not change,
-and if it does, then most likely you have an incorrect reference to an
-uninitialized value.
+First, there is no requirement for the pragma to be used uniformly in all units
+of a partition. In particular, it is fine to use this just for some or all of
+the application units of a partition, without needing to recompile the run-time
+library. In the case where some units are compiled with the pragma, and some
+without, then a declaration of a variable where the type is defined in package
+Standard or is locally declared will always be subject to initialization, as
+will any declaration of a scalar variable. For composite variables, whether the
+variable is initialized may also depend on whether the package in which the
+type of the variable is declared is compiled with the pragma.
-It is even possible to change the value at execution time eliminating even
-the need to rebind with a different switch using an environment variable.
-See the GNAT User's Guide for details.
+The other important difference is that the programmer can control the value
+used for initializing scalar objects. This effect can be achieved in several
+different ways:
+
+* At compile time, the programmer can specify the invalid value for a
+ particular family of scalar types using the optional arguments of the pragma.
+
+ The compile-time approach is intended to optimize the generated code for the
+ pragma, by possibly using fast operations such as ``memset``.
+
+* At bind time, the programmer has several options:
+
+ * Initialization with invalid values (similar to Normalize_Scalars, though
+ for Initialize_Scalars it is not always possible to determine the invalid
+ values in complex cases like signed component fields with nonstandard
+ sizes).
+
+ * Initialization with high values.
+
+ * Initialization with low values.
+
+ * Initialization with a specific bit pattern.
+
+ See the GNAT User's Guide for binder options for specifying these cases.
+
+ The bind-time approach is intended to provide fast turnaround for testing
+ with different values, without having to recompile the program.
+
+* At execution time, the programmer can speify the invalid values using an
+ environment variable. See the GNAT User's Guide for details.
+
+ The execution-time approach is intended to provide fast turnaround for
+ testing with different values, without having to recompile and rebind the
+ program.
+
+Note that pragma ``Initialize_Scalars`` is particularly useful in conjunction
+with the enhanced validity checking that is now provided in GNAT, which checks
+for invalid values under more conditions. Using this feature (see description
+of the *-gnatV* flag in the GNAT User's Guide) in conjunction with pragma
+``Initialize_Scalars`` provides a powerful new tool to assist in the detection
+of problems caused by uninitialized variables.
-Note that pragma ``Initialize_Scalars`` is particularly useful in
-conjunction with the enhanced validity checking that is now provided
-in GNAT, which checks for invalid values under more conditions.
-Using this feature (see description of the *-gnatV* flag in the
-GNAT User's Guide) in conjunction with
-pragma ``Initialize_Scalars``
-provides a powerful new tool to assist in the detection of problems
-caused by uninitialized variables.
-
-Note: the use of ``Initialize_Scalars`` has a fairly extensive
-effect on the generated code. This may cause your code to be
-substantially larger. It may also cause an increase in the amount
-of stack required, so it is probably a good idea to turn on stack
-checking (see description of stack checking in the GNAT
-User's Guide) when using this pragma.
+Note: the use of ``Initialize_Scalars`` has a fairly extensive effect on the
+generated code. This may cause your code to be substantially larger. It may
+also cause an increase in the amount of stack required, so it is probably a
+good idea to turn on stack checking (see description of stack checking in the
+GNAT User's Guide) when using this pragma.
.. _Pragma-Initializes:
taken from the string provided.
@end itemize
-This pragma may appear anywhere that a pragma is valid. In particular, it
+This pragma may appear anywhere that a pragma is valid. In particular, it
can be used as a configuration pragma in the @code{gnat.adc} file, in which
case it applies to all subsequent compilations, or it can be used as a program
unit pragma, in which case it only applies to the current unit, or it can
Syntax:
@example
-pragma Initialize_Scalars;
+pragma Initialize_Scalars
+ [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ];
+
+TYPE_VALUE_PAIR ::=
+ SCALAR_TYPE => static_EXPRESSION
+
+SCALAR_TYPE :=
+ Short_Float
+| Float
+| Long_Float
+| Long_Long_Flat
+| Signed_8
+| Signed_16
+| Signed_32
+| Signed_64
+| Unsigned_8
+| Unsigned_16
+| Unsigned_32
+| Unsigned_64
@end example
-This pragma is similar to @code{Normalize_Scalars} conceptually but has
-two important differences. First, there is no requirement for the pragma
-to be used uniformly in all units of a partition, in particular, it is fine
-to use this just for some or all of the application units of a partition,
-without needing to recompile the run-time library.
-
-In the case where some units are compiled with the pragma, and some without,
-then a declaration of a variable where the type is defined in package
-Standard or is locally declared will always be subject to initialization,
-as will any declaration of a scalar variable. For composite variables,
-whether the variable is initialized may also depend on whether the package
-in which the type of the variable is declared is compiled with the pragma.
-
-The other important difference is that you can control the value used
-for initializing scalar objects. At bind time, you can select several
-options for initialization. You can
-initialize with invalid values (similar to Normalize_Scalars, though for
-Initialize_Scalars it is not always possible to determine the invalid
-values in complex cases like signed component fields with non-standard
-sizes). You can also initialize with high or
-low values, or with a specified bit pattern. See the GNAT
-User's Guide for binder options for specifying these cases.
-
-This means that you can compile a program, and then without having to
-recompile the program, you can run it with different values being used
-for initializing otherwise uninitialized values, to test if your program
-behavior depends on the choice. Of course the behavior should not change,
-and if it does, then most likely you have an incorrect reference to an
-uninitialized value.
-
-It is even possible to change the value at execution time eliminating even
-the need to rebind with a different switch using an environment variable.
-See the GNAT User's Guide for details.
+This pragma is similar to @code{Normalize_Scalars} conceptually but has two
+important differences.
+
+First, there is no requirement for the pragma to be used uniformly in all units
+of a partition. In particular, it is fine to use this just for some or all of
+the application units of a partition, without needing to recompile the run-time
+library. In the case where some units are compiled with the pragma, and some
+without, then a declaration of a variable where the type is defined in package
+Standard or is locally declared will always be subject to initialization, as
+will any declaration of a scalar variable. For composite variables, whether the
+variable is initialized may also depend on whether the package in which the
+type of the variable is declared is compiled with the pragma.
+
+The other important difference is that the programmer can control the value
+used for initializing scalar objects. This effect can be achieved in several
+different ways:
+
+
+@itemize *
+
+@item
+At compile time, the programmer can specify the invalid value for a
+particular family of scalar types using the optional arguments of the pragma.
+
+The compile-time approach is intended to optimize the generated code for the
+pragma, by possibly using fast operations such as @code{memset}.
+
+@item
+At bind time, the programmer has several options:
+
+
+@itemize *
+
+@item
+Initialization with invalid values (similar to Normalize_Scalars, though
+for Initialize_Scalars it is not always possible to determine the invalid
+values in complex cases like signed component fields with nonstandard
+sizes).
+
+@item
+Initialization with high values.
+
+@item
+Initialization with low values.
+
+@item
+Initialization with a specific bit pattern.
+@end itemize
+
+See the GNAT User's Guide for binder options for specifying these cases.
+
+The bind-time approach is intended to provide fast turnaround for testing
+with different values, without having to recompile the program.
+
+@item
+At execution time, the programmer can speify the invalid values using an
+environment variable. See the GNAT User's Guide for details.
+
+The execution-time approach is intended to provide fast turnaround for
+testing with different values, without having to recompile and rebind the
+program.
+@end itemize
+
+Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction
+with the enhanced validity checking that is now provided in GNAT, which checks
+for invalid values under more conditions. Using this feature (see description
+of the @emph{-gnatV} flag in the GNAT User's Guide) in conjunction with pragma
+@code{Initialize_Scalars} provides a powerful new tool to assist in the detection
+of problems caused by uninitialized variables.
-Note that pragma @code{Initialize_Scalars} is particularly useful in
-conjunction with the enhanced validity checking that is now provided
-in GNAT, which checks for invalid values under more conditions.
-Using this feature (see description of the @emph{-gnatV} flag in the
-GNAT User's Guide) in conjunction with
-pragma @code{Initialize_Scalars}
-provides a powerful new tool to assist in the detection of problems
-caused by uninitialized variables.
-
-Note: the use of @code{Initialize_Scalars} has a fairly extensive
-effect on the generated code. This may cause your code to be
-substantially larger. It may also cause an increase in the amount
-of stack required, so it is probably a good idea to turn on stack
-checking (see description of stack checking in the GNAT
-User's Guide) when using this pragma.
+Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the
+generated code. This may cause your code to be substantially larger. It may
+also cause an increase in the amount of stack required, so it is probably a
+good idea to turn on stack checking (see description of stack checking in the
+GNAT User's Guide) when using this pragma.
@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{84}
projects / gcc.git / commitdiff