Skip to content

Add Spec Glossary #1537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Add Spec Glossary #1537

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dcdeb9c
Add some spec glossary terms to the reference glossary
chorman0773 Jul 18, 2024
e1fd482
Merge branch 'rust-lang:master' into spec-glossary
chorman0773 Jul 18, 2024
f4ab575
Fix formatting of glossary.md
chorman0773 Jul 18, 2024
8f464ba
Make suggested glossary changes from PR Comments
chorman0773 Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions src/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,29 @@
# Glossary

## Terms used in the Specification
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you say more about why this would be separated?

I think that generally we shouldn't need to separate this out. I don't think there should be terms here that aren't used in the specification (unless they are aliases for ones that are).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm back and forth on this.

The main thing I would put in the section would be prescriptive terms, rather than semantic terms (IE. terms used to express the requirements of the spec, not terms that refer to a construct). IE. a term like "function" wouldn't go in this section, but would go into the rest of the glossary.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be something to discuss tomorrow.


### Ill-formed Program
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Ill-formed Program
### Ill-formed program

Headings should be in sentence case.


A Rust Program is ill-formed if it violates a statically set constraint placed on it by the language.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why some of these words are being capitalized. Also, I think this can be reworded to simplify a little.

Suggested change
A Rust Program is ill-formed if it violates a statically set constraint placed on it by the language.
A Rust program is ill-formed if it violates a static constraint of the language.

I'm also trying to figure out, what is a "static constraint"? How would this contrast with a "dynamic constraint"? Would be possible to state it as "violates a rule of the language"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's to separate out from dynamic constraints that lead to undefined behaviour (such as dereferencing a null pointer).

Unless otherwise statement explicitly an implementation shall issue an appropriate diagnostic for an ill-formed program and shall not translate such a program.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is some awkward wording here.

Suggested change
Unless otherwise statement explicitly an implementation shall issue an appropriate diagnostic for an ill-formed program and shall not translate such a program.
Unless otherwise stated explicitly, an implementation shall issue an appropriate diagnostic for an ill-formed program and shall not translate such a program.

However, as an alternative, can this be stated as:

Suggested change
Unless otherwise statement explicitly an implementation shall issue an appropriate diagnostic for an ill-formed program and shall not translate such a program.
Unless otherwise stated, it is an error to have an ill-formed program.

Although I don't know when we would ever state that it is not an error. Can you give an example? Is this referring to things like undefined-behavior?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See "No Diagnostic Required"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, the proposed wording is a bit ambiguous here - you could argue it's always an error to have such a program (even if the constraint the program violated is one for which "no diagnostic is required").


#### No Diagnostic Required
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I'm still struggling with understanding what this means.

Is this trying to say that some rules may result in a warning, but otherwise isn't enforced?

If so, I don't think we have yet agreed on an approach for how to document warnings. In general, we have avoided all warnings in the reference. There are a few exceptions when it is directly relevant to the language (like the diagnostic chapter), or when we have felt the warning is very important (like unsafe_op_in_unsafe_fn, though that is arguable if it is appropriate.

Copy link
Contributor Author

@chorman0773 chorman0773 Jul 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lints are separate from this.
The compiler can issue a hard error (fail to compile), warn (lint, fcw, etc.), or silently accept it. This isn't for things that you'd lint on, though, this is particularily for things may horribly break the program, but can't be easily (or at all) detected and diagnosed. For example, asm!(".section .data");, which can cause the rest of the function (and possibly even entire other functions) to be emitted in the .data section, far far away from where the code is expected to be.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I'm still not understanding what this means. I don't see why there would be rules that we want to say "this may or may not compile".

I'm trying to understand, is this related to undefined behavior?

I see in the assembly chapter, asm.invocation.prefix-instr mentions this. I'm confused because the original text had that in a list of things the programmer must not do to avoid undefined behavior. The new text doesn't seem to be organized that way, and I'm having a hard time understanding why that changed or how it relates to the original text.

Copy link
Contributor Author

@chorman0773 chorman0773 Jul 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's basically super UB. With UB it's fine to have it in the program as long as it's not evaluated*. With IF-NDR, it's not fine to have it in the program.

That particular list (in the original ASM chapter) is particularly bad, because it had quite a few things mixed together, including things that obviously are not fine in unevaluated code because they have potentially invalid global implications - for example, asm!(".section .data") as mentioned, which switches to a section called .data and depending on how inline asm is implemented, that could affect just the rest of the block, all inline assembly in the crate, or potentially even the rest of the function and all others in the crate.

For the same reason, trying to put a function into .data is likely fundamentally broken, because depending on the platform, the binary format, and the linker, that could end up in an RWX section, an RW section, and RX section (and mutable data is placed in the same RX section), or outright being rejected by the linker or loader (whether or not the function is even called), but it's difficult to diagnose this in the general case.


When No Diagnostic is Required for a static constraint, the implementation may issue a diagnostic for the violation, and may translate the program.
If such a program is succesfully translated, no constraints are placed on the result of executing the program.

> [!NOTE]
> The constraint which is modified by the phrase "No Diagnostic Required" may be defined implicitly, such as with the term "shall", rather than explicitly stating that the program is ill-formed.

> [!NOTE]
> Such constraints are used only when it may be unreasonable or impossible to check the constraints statically, and where the result of violating the constraints makes it impossible to ensure the required behaviour of the program

### Shall

The word "shall" is a static constraint placed upon the program. A program that violates a constraint that uses "shall" is ill-formed.
Comment on lines +26 to +28
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't entirely object to specifying this, but I just want to call out that it seems unusual to do so. At least, I have not seen any other languages do that. Is there a precedent that shows this needing definition or way this could be confusing otherwise?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought C++ did but I checked and am incorrect.
I know C does so implicitly. I think it's useful to call out the term shall as specifically meaning a static constraint, because it could reasonably mean either.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Ada standards do (since Ada 95; Ada 83 used "must"). See eg Ada 2012 §1.1.5:3.


## Rust Specific Terms

### Abstract syntax tree

An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of
Expand Down Expand Up @@ -105,6 +129,7 @@ are also considered local. Fundamental type constructors cannot [cover](#uncover
Any time the term "covered type" is used,
the `T` in `&T`, `&mut T`, `Box<T>`, and `Pin<T>` is not considered covered.


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a stray newline?

### Inhabited

A type is inhabited if it has constructors and therefore can be instantiated. An inhabited type is
Expand Down