AI22-0055-1/06

AI22-0055-1

!standard 1.1.2(37) 24-04-16 AI22-0055-1/06

!standard 3.9(27/5)

!standard 4.6(58.6/5)

!standard 4.6(62)

!standard 7.6.1(20.2/3)

!standard 7.6.1(24)

!standard 9.8(22/5)

!standard 9.9(5)

!standard 9.9(7/5)

!standard 9.9(8/5)

!standard 11.4.2(28/5)

!standard 12.4(12)

!standard 12.6(10.2/2)

!standard 12.6(12)

!standard 13.9.2(3/4)

!standard 13.9.2(14/5)

!standard A.5.2(47)

!standard A.5.2(50/5)

!standard A.5.2(52/5)

!standard A.5.2(53/2)

!standard A.5.2(54)

!standard A.16(126/2)

!standard A.16(131/5)

!standard B.3.2(43)

!standard C.3.1(21)

!standard C.3.1(23/5)

!standard D.13(9/5)

!standard D.13(12/5)

!class binding interpretation 22-11-30

!status Revision-202Y 24-02-22

!status WG9 Approved 24-06-10

!status ARG Approved 15-0-0 24-02-22

!status work item 22-11-30

!status received 22-11-04

!priority Low

!difficulty Easy

!qualifier Clarification^[a]

!subject Usage Advice

!summary

Move certain NOTEs into a new “Usage” section.

!issue

Various notes in the Standard provide advice to the Ada user. These notes use wording like "should", "recommended", or "preferred". None of these wordings are allowed in notes.

We need a different approach for handling advice on writing Ada programs.

!recommendation

(See Summary.)

!wording

[Editor's note: The original source of this list of notes are those that were rejected in the FDIS by the ISO editors. Those were removed from the final FDIS (but remain, of course, in the RM). Some of the notes below reference phrases that were highlighted by the ISO editors.

I've included some usage notes whose rewording late in the Ada 2022 process were not rejected. These still were originally intended to be usage advice, and should be handled accordingly in future Ada standards. However, they remain in the FDIS and RM as reworded. All of these are marked "was not flagged", meaning not flagged by the ISO editors.]

Add after 1.1.2(37):

Usage

Advice and notes on the usage of the Ada programming language. This material is informative.

Modify 3.9(27/5):

{Usage}

[NOTE 1 ]A type declared with the reserved word tagged {should}[is] normally {be }declared in a package_specification, so that new primitive subprograms can be declared for it.

[This was not flagged, but it was reworded and still reads as a recommendation. We’ve reverted to the original wording which is more understandable.]

Add after 4.6(58.6/5):

Usage

The constraint of the target subtype has no effect for a type_conversion of an elementary type passed as an out parameter. Hence, it is recommended that the first subtype of the elementary type be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal in out objects).

Delete 4.6(62):

NOTE 3 The constraint of the target subtype has no effect for a type_conversion of an elementary type passed as an out parameter. Hence, it is recommended that the first subtype be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal in out objects).

["it is recommended that"; this is "Usage Advice". A rewrite would lose the point. The Editor suggests clarifying which "first subtype" is being recommended in this note; that was done above. There are a lot of first subtypes in an Ada program. We have to move the Usage above all of the other notes.]

Add after 7.6.1(20.2/3):

Usage

The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure should be designed to have no ill effect if it is applied a second time to the same object.

Delete 7.6.1(24):

NOTE 4 The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure is ideally designed to have no ill effect if it is applied a second time to the same object.

[This was not flagged; but it was reworded and it still reads as a weak recommendation. We’ve reverted to the original wording which is more understandable. We have to move the Usage above all of the other notes; AARM 24.a and 24.b need to move with it.]

Modify 9.8(22/5):

{Usage}

[NOTE 1 ]An abort_statement {should be}[is best] used only in situations requiring unconditional termination.

[This was not flagged; but it was reworded and it still reads as a weak recommendation. We’ve reverted to the original wording which is more understandable.]

Add after 9.9 (5):

Usage

Within task units, algorithms interrogating the attribute E'Count should take precautions to allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with timed_entry_calls. Similarly, a conditional_entry_call can briefly increase this value, even if the conditional call is not accepted.

Within protected units, algorithms interrogating the attribute E'Count in the entry_barrier for the entry E should take precautions to allow for the evaluation of the condition of the barrier both before and after queuing a given caller.

Delete 9.9(7/5):

NOTE 2 Within task units, by interrogating the attribute E'Count an algorithm can allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with timed_entry_calls. A conditional_entry_call can also briefly increase this value, even if the conditional call is not accepted.

Delete 9.9(8/5)

NOTE 3 Within protected units, by interrogating the attribute E'Count in the entry_barrier for the entry E an algorithm can allow for the evaluation of the condition of the barrier both before and after queuing a given caller.

[The rewording of these two was not flagged, but it rather lost the point, and the original wording given here is clearly a usage recommendation. We have to move these above the other note.]

Modify 11.4.2(28/5):

{Usage}

[NOTE Normally, the]{The} boolean expression in a pragma Assert should not call functions that have significant side effects when the result of the expression is True, so that the particular assertion policy in effect will not affect normal operation of the program.

["should"; this is clearly a usage recommendation. The "Normally" seems unneeded in a statement that is already advice rather than a command -- one only needs a single weasel word.]

Modify 12.4(12):

{Usage}

[NOTE ]The constraints that apply to a generic formal object of mode in out are those of the corresponding generic actual parameter (not those implied by the subtype_mark that appears in the formal_object_declaration). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object.

["it is recommended that". The last sentence here is "usage advice" (see above). Rewriting probably will not keep the point.]

Add after 12.6(10.2/2):

Usage

The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the subprogram_specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.

Delete 12.6(12):

NOTE 2 The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the _specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.

["it is recommended that". Usage advice. We have to move this above the first note.]

Add after 13.9.2(3/4):

Usage

The Valid attribute can be used to check the result of calling an instance of Unchecked_Conversion (or any other operation that can return invalid values). However, an exception handler should also be provided because implementations are permitted to raise Constraint_Error or Program_Error if they detect the use of an invalid representation (see 13.9.1).

Delete 13.9.2(14/5):

NOTE 3 The Valid attribute can be used to check the result of calling an instance of Unchecked_Conversion (or any other operation that can return invalid values). However, an exception handler should also be provided because implementations are permitted to raise Constraint_Error or Program_Error if they detect the use of an invalid representation (see 13.9.1).

[The second sentence (original wording here) is clearly a usage recommendation; the rewording of "is still useful" wasn't flagged but still is a weak recommendation. The original wording is better and thus we use it here. We have to move this above the other two notes.]

Add after A.5.2(47):

Usage

A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they assume that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some range is necessary, the application should use one of the Random functions in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random.

Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation

-Log(Random(G) + Float'Model_Small)

where Log comes from Numerics.Elementary_Functions (see A.5.1); in this expression, the addition of Float'Model_Small avoids the exception that would be raised were Log to be given the value zero, without affecting the result (in most implementations) when Random returns a nonzero value.

Delete A.5.2(50/5):

NOTE 3 A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they assume that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some range is necessary, the application should use one of the Random functions in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random.

[“should”, a recommendation. We’ve moved the related following note as well, as well as partially reverting the wording to closer to the original Ada 2012 wording.]

Delete A.5.2(52/5):

NOTE 4 Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation

Delete A.5.2(53/2):

-Log(Random(G) + Float'Model_Small)

Delete A.5.2(54)

Add after A.16(126/2):

Usage

To move a file or directory to a different location, use Rename. Most target systems will allow renaming of files from one directory to another. If the target file or directory can already exist, it should be deleted first.

Delete A.16(131/5):

NOTE 5 To move a file or directory to a different location, use Rename. Most target systems will allow renaming of files from one directory to another. If the target file or directory can already exist, delete it first.

["delete it first" was highlighted here, without comment. Not sure what the complaint is. We’ve reverted this to the original wording of "it should be deleted first", which makes it clear usage advice.]

Modify B.3.2(43):

{Usage}

[NOTE ]To compose a Pointer from an Element_Array, use 'Access on the first element. For example (assuming appropriate instantiations):

["use" is highlighted here without comment. Not sure what is wrong here, but this is again (weak) usage advice.]

Add after C.3.1(21):

Usage

A protected object that has a (protected) procedure attached to an interrupt should have a ceiling priority that is at least as high as the highest processor priority at which that interrupt will ever be delivered.

Delete C.3.1(23/5):

NOTE 2 For a protected object that has a (protected) procedure attached to an interrupt, the correct ceiling priority is at least as high as the highest processor priority at which that interrupt will ever be delivered.

[Not flagged, this was reworded to remove "should", but it still is clearly a usage recommendation. We’ve reverted the wording as “should” is clearer.]

Add after D.13(9/5):

Usage

It is not recommended to specify the CPU of a task to be Not_A_Specific_CPU when the Ravenscar or Jorvik profile is in effect. How a partition executes strongly depends on the assignment of tasks to CPUs.

Delete D.13(12/5):

NOTE 3 It is not recommended to specify the CPU of a task to be Not_A_Specific_CPU when the Ravenscar or Jorvik profile is in effect. How a partition executes strongly depends on the assignment of tasks to CPUs.

["it is not recommended". This is usage advice.]

!discussion

The Ada Reference Manual (RM) has reserved normative recommendations to apply only to implementers (that is, the people who are attempting to build an Ada processor that conforms to the Standard). Words like "should" and "it is recommended" are always interpreted to apply to implementers.

In order to provide advice on using the Ada language, a number of notes (which are considered non-normative) are included in the RM. These also use words like "should" and "it is recommended" but are clearly not intended to be part of the Standard.

Unfortunately, the "JTC1 Directives, Part 2" (the document which gives the rules for drafting JTC1 standards), no longer allows requirements or recommendations to be given in notes. All of the notes that give usage advice clearly violate this rule, and cannot be reworded to avoid the restrictions without eliminating the advice that they are intended to give. We need to do something about this.

The "Directives" suggest that a Standard be aimed at a single audience, and that other standards (or parts of standards) be produced for other audiences. That would suggest creating an additional part specifically to give usage advice. However, doing that would either end up with a *very* skinny document, or would require a lot of additional work to define style recommendations to flesh out the document. This does not seem to be a topic on which to expend scarce resources.

If we want to continue to have the notes in the RM (and Standard), then we need to move them to the body of the RM. To do that, we would need to define a category subheading ("Usage" is what is recommended here). Then we can use wording like "should" with the audience clearly indicated. We also recommend that we create an additional Annex that summarizes that advice in one place (much as we do for Implementation Advice), with an introduction of

something like "This annex summarizes the advice given for the usage of the Ada language in this document."

A third alternative would be to simply put all of these notes into a dedicated Annex. That would meet the directives. However, it would mean that the usage information would be far away from the definition of a feature. It seems unlikely that someone reading about the random number package would remember to look in the Usage Advice annex to see if there was anything relevant (especially as there often would not be any advice).

A fourth alternative would be to remove these notes permanently from the RM, and simply move them to the AARM in a new category "Usage". That could be indexed so that users can find it. However, the AARM is aimed at implementers and language lawyers, not ordinary users. So doing this would mean that the notes would not be seen by the intended audience.

[Editor's note: For the purposes of the Ada 2022 Standard, we just deleted the offending notes, leaving the RM alone. It was too late to make a major restructuring of the standard (adding new subheadings, normative wording, and an Annex). When it says above that a note was reverted in Ada 2022, it means in the Ada 2022 RM (such notes do not appear in the Ada 2022 Standard).]

!corrigendum 1.1.2(37)

@dinsa

Optional advice given to the implementer. The word “should” is used to indicate that the advice is a recommendation, not a requirement. It is implementation defined whether or not a given recommendation is obeyed.

@dinst

@s8{@i{Usage}}

Advice and notes on the usage of the Ada programming language. This material is informative.

!corrigendum 3.9(27/5)

@drepl

@xindent{@s9{NOTE 1 @ A type declared with the reserved word @b{tagged} is normally declared in a @fa{package_specification}, so that new primitive subprograms can be declared for it.}}

@dby

@s8{@i{Usage}}

A type declared with the reserved word @b{tagged} should normally be declared in a @fa{package_specification}, so that new primitive subprograms can be declared for it.

!corrigendum 4.6(58.6/5)

@dinsa

If a new object is created, then the initialization of that object is an assignment operation.

@dinst

@s8{@i{Usage}}

The constraint of the target subtype has no effect for a @fa{type_conversion} of an elementary type passed as an @b{out} parameter. Hence, it is recommended that the first subtype of the elementary type be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal @b{in out} objects).

!corrigendum 4.6(62)

@ddel

@xindent{@s9{NOTE 3 @ The constraint of the target subtype has no effect for a @fa{type_conversion} of an elementary type passed as an @b{out} parameter. Hence, it is recommended that the first subtype be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal @b{in out} objects).}}

!corrigendum 7.6.1(20.2/3)

@dinsa

The implementation may finalize objects created by @fa{allocator}s for an access type whose storage pool supports subpools (see 13.11.4) as if the objects were created (in an arbitrary order) at the point where the storage pool was elaborated instead of at the first freezing point of the access type.

@dinst

@s8{@i{Usage}}

!corrigendum 7.6.1(24)

@ddel

@xindent{@s9{NOTE 4 @ The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure is ideally designed to have no ill effect if it is applied a second time to the same object.}}

!corrigendum 9.8(22/5)

@drepl

@xindent{@s9{NOTE @ An @fa{abort_statement} is best used only in situations requiring unconditional termination.}}

@dby

@s8{@i{Usage}}

An @fa{abort_statement} should be used only in situations requiring unconditional termination.

!corrigendum 9.9(5)

@dinsa

@xhang{@xterm{E'Count}

Yields the number of calls presently queued on the entry E of the current instance of the unit. The value of this attribute is of the type @i{universal_integer}.}

@dinst

@s8{@i{Usage}}

Within task units, algorithms interrogating the attribute E'Count should take precautions to allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with @fa{timed_entry_call}s. Similarly, a @fa{conditional_entry_call} can briefly increase this value, even if the conditional call is not accepted.

Within protected units, algorithms interrogating the attribute E'Count in the @fa{entry_barrier} for the entry E should take precautions to allow for the evaluation of the @fa{condition} of the barrier both before and after queuing a given caller.

!corrigendum 9.9(7/5)

@ddel

@xindent{@s9{NOTE 2 @ Within task units, by interrogating the attribute E'Count an algorithm can allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with @fa{timed_entry_call}s. A @fa{conditional_entry_call} can also briefly increase this value, even if the conditional call is not accepted.}}

!corrigendum 9.9(8/5)

@ddel

@xindent{@s9{NOTE 2 @ Within protected units, by interrogating the attribute E'Count in the @fa{entry_barrier} for the entry E an algorithm can allow for the evaluation of the @fa{condition} of the barrier both before and after queuing a given caller.}}

!corrigendum 11.4.2(28/5)

@drepl

@xindent{@s9{NOTE @ Normally, the boolean expression in a @fa{pragma} Assert should not call functions that have significant side effects when the result of the expression is True, so that the particular assertion policy in effect will not affect normal operation of the program.}}

@dby

@s8{@i{Usage}}

The boolean expression in a @fa{pragma} Assert should not call functions that have significant side effects when the result of the expression is True, so that the particular assertion policy in effect will not affect normal operation of the program.

!corrigendum 12.4(12)

@drepl

@xindent{@s9{NOTE @ The constraints that apply to a generic formal object of mode @b{in out} are those of the corresponding generic actual parameter (not those implied by the @fa{subtype_mark} that appears in the @fa{formal_object_declaration}). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object.}}

@dby

@s8{@i{Usage}}

The constraints that apply to a generic formal object of mode @b{in out} are those of the corresponding generic actual parameter (not those implied by the @fa{subtype_mark} that appears in the @fa{formal_object_declaration}). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object.

!corrigendum 12.6(10.2/2)

@dinsa

The subprogram declared by a @fa{formal_abstract_subprogram_declaration} with a controlling type @i{T} is a dispatching operation of type @i{T}.

@dinst

@s8{@i{Usage}}

The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding @fa{subtype_mark} in the @fa{subprogram_specification} of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.

!corrigendum 12.6(12)

@ddel

@xindent{@s9{NOTE 2 @ The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding @fa{subtype_mark} in the @fa{_specification} of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.}}

!corrigendum 13.9.2(3/4)

@dinsa

@xhang{@xterm{X'Valid}Yields True if and only if the object denoted by X is normal, has a valid representation, and then, if the preceding conditions hold, the value of X also satisfies the predicates of the nominal subtype of X. The value of this attribute is of the predefined type Boolean.}

@dinst

@s8{@i{Usage}}

!corrigendum 13.9.2(14/5)

@ddel

@xindent{@s9{NOTE 3 @ The Valid attribute can be used to check the result of calling an instance of Unchecked_Conversion (or any other operation that can return invalid values). However, an exception handler is still useful because implementations are permitted to raise Constraint_Error or Program_Error if they detect the use of an invalid representation (see 13.9.1).}}

!corrigendum A.5.2(47)

@dinsa

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.

@dinss

@s8{@i{Usage}}

Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation

@xcode{ -Log(Random(G) + Float'Model_Small)}

!corrigendum A.5.2(50/5)

@ddel

@xindent{@s9{NOTE 3 @ A given implementation of the Random function in Numerics.Float_Random is not guaranteed to be capable of delivering the values 0.0 or 1.0. Applications will be more portable if they assume that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some range is necessary, the application should use one of the Random functions in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random.}}

!corrigendum A.5.2(52/5)

@ddel

@xindent{@s9{NOTE 4 @ Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation}}

!corrigendum A.5.2(53/2)

@ddel

@xindent{@s9{@fc{ -Log(Random(G) + Float'Model_Small)}}}

!corrigendum A.5.2(54)

@ddel

@xindent{@s9{where Log comes from Numerics.Elementary_Functions (see A.5.1); in this expression, the addition of Float'Model_Small avoids the exception that would be raised were Log to be given the value zero, without affecting the result (in most implementations) when Random returns a nonzero value.}}

!corrigendum A.16(126/2)

@dinsa

Rename should be supported at least when both New_Name and Old_Name are simple names and New_Name does not identify an existing external file.

@dinst

@s8{@i{Usage}}

!corrigendum A.16(131/5)

@ddel

@xindent{@s9{NOTE 5 To move a file or directory to a different location, use Rename. Most target systems will allow renaming of files from one directory to another. If the target file or directory can already exist, delete it first.}}

!corrigendum B.3.2(43)

@drepl

@xindent{@s9{NOTE @ To compose a Pointer from an Element_Array, use 'Access on the first element. For example (assuming appropriate instantiations):}}

@dby

@s8{@i{Usage}}

To compose a Pointer from an Element_Array, use 'Access on the first element. For example (assuming appropriate instantiations):

!corrigendum C.3.1(21)

@dinsa

Whenever practical, the implementation should detect violations of any implementation-defined restrictions before run time.

@dinst

@s8{@i{Usage}}

!corrigendum C.3.1(23/5)

@ddel

@xindent{@s9{NOTE 2 @ For a protected object that has a (protected) procedure attached to an interrupt, the correct ceiling priority is at least as high as the highest processor priority at which that interrupt will ever be delivered.}}

!corrigendum D.13(9/5)

@dinsa

On a multiprocessor system, an implementation should support a fully partitioned approach if one of these profiles is specified. Each processor should have separate and disjoint ready queues.

@dinst

@s8{@i{Usage}}

!corrigendum D.13(12/5)

@ddel

@xindent{@s9{NOTE 3 @ It is not recommended to specify the CPU of a task to be Not_A_Specific_CPU when the Ravenscar or Jorvik profile is in effect. How a partition executes strongly depends on the assignment of tasks to CPUs.}}

!ACATS test

None needed, this is not intended to be testable text (even if included in the text of the RM).

!appendix

[a]There are only three allowed "qualifiers", we can't invent one. This is not an error or omission, so this is a clarification by default.