This page is a snapshot from the LWG issues list, see the Library Active Issues List for more information and the meaning of Resolved status.

3168. Expects: element should be specified in one place

Section: 16.3.2.4 [structure.specifications], 99 [res.on.required] Status: Resolved Submitter: Geoffrey Romer Opened: 2018-11-21 Last modified: 2020-07-18

Priority: 2

View other active issues in [structure.specifications].

View all other issues in [structure.specifications].

View all issues with Resolved status.

Discussion:

16.3.2.4 [structure.specifications]/p3.4 specifies the Expects: element as "the conditions (sometimes termed preconditions) that the function assumes to hold whenever it is called". This is nonsensical (functions can't "assume" things because they're not sentient), and more to the point it says nothing about what happens if those conditions don't hold. This is a serious problem because the whole point of introducing Expects: was to correct the vagueness of Requires: on exactly that point.

99 [res.on.required]/p2 is more explicit: "Violation of any preconditions specified in a function's Expects: element results in undefined behavior." However, I think putting the actual meaning of the Expects: element in a subclause called "Requires paragraph", 21 pages away from where Expects: is nominally specified, is asking too much of the reader. Splitting the specification of Requires: into two places 21 pages apart also seems needlessly obtuse, but that's less pressing since Requires: should be going away soon.

[2018-11 Reflector prioritization]

Set Priority to 2

[2019-02; Kona Wednesday night issue processing]

Alternate wording discussed; Marshall to check with Geoffrey and vote on reflector.

[2019 Cologne Wednesday night]

Revisit once the appropriate "Mandating" paper has landed

[2020-06; telecon and reflector discussion]

Changing Expects: to Preconditions: doesn't change the fact that the specification is split across two subclauses. Resolved editorially by integrating [res.on.expects] into [structure.specifications].

Proposed resolution:

This wording is relative to N4778.

[Drafting Note: I have prepared two mutually exclusive options, depicted below by Option A and Option B, respectively. In case the committee would prefer to leave "Requires" alone, Option B describes just the "Expects" edits, as an alternate P/R]

Option A

  1. Change 16.3.2.4 [structure.specifications] as indicated:

    -3- Descriptions of function semantics contain the following elements (as appropriate):(footnote)

    1. (3.1) — Requires: the preconditions for calling the function.the conditions that are required to hold when the function is called in order for the call to successfully complete. [Note: When these conditions are violated, the function's Throws: element may specify throwing an exception. Otherwise, the behavior is undefined. — end note]

    2. (3.2) — Constraints: […]

    3. (3.3) — Mandates: […]

    4. (3.4) — Expects: the conditions (sometimes termed preconditions) that the function assumes to hold whenever it is calledare required to hold when the function is called in order for the call to have well-defined behavior. [Example: An implementation might express such conditions via an attribute such as [[expects]] ( [dcl.attr.contract]). However, some such conditions might not lend themselves to expression via code. — end example]

  2. Delete 99 [res.on.required] in it's entirety as indicated:

    15.5.4.11 Requires paragraph [res.on.required]

    -1- Violation of any preconditions specified in a function's Requires: element results in undefined behavior unless the function's Throws: element specifies throwing an exception when the precondition is violated.

    -2- Violation of any preconditions specified in a function's Expects: element results in undefined behavior.

Option B

  1. Change 16.3.2.4 [structure.specifications] as indicated:

    -3- Descriptions of function semantics contain the following elements (as appropriate):(footnote)

    1. (3.1) — Requires: the preconditions for calling the function.

    2. (3.2) — Constraints: […]

    3. (3.3) — Mandates: […]

    4. (3.4) — Expects: the conditions (sometimes termed preconditions) that the function assumes to hold whenever it is calledare required to hold when the function is called in order for the call to have well-defined behavior. [Example: An implementation might express such conditions via an attribute such as [[expects]] ( [dcl.attr.contract]). However, some such conditions might not lend themselves to expression via code. — end example]

  2. Change 99 [res.on.required] as indicated:

    -1- Violation of any preconditions specified in a function's Requires: element results in undefined behavior unless the function's Throws: element specifies throwing an exception when the precondition is violated.

    -2- Violation of any preconditions specified in a function's Expects: element results in undefined behavior.