mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-11-22 17:32:38 +00:00
Includes changes from accepted proposals: - #3762 - #3763 - #3980 - #5366 Examples from the proposals has been updated to reflect changes made in later proposals, such as using `ref` instead of `addr`. Links from #3762 have been changed to point to the version of the code from when the PR was merged. Assisted-by: Gemini via Antigravity --------- Co-authored-by: Josh L <josh11b@users.noreply.github.com> Co-authored-by: Geoff Romer <gromer@google.com>
464 lines
18 KiB
Markdown
464 lines
18 KiB
Markdown
# Declaring entities
|
|
|
|
<!--
|
|
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
|
|
Exceptions. See /LICENSE for license information.
|
|
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
-->
|
|
|
|
<!-- toc -->
|
|
|
|
## Table of contents
|
|
|
|
- [Overview](#overview)
|
|
- [Matching redeclarations of an entity](#matching-redeclarations-of-an-entity)
|
|
- [Details](#details)
|
|
- [Modifier keywords](#modifier-keywords)
|
|
- [Syntactic matching and scopes](#syntactic-matching-and-scopes)
|
|
- [`extern` and `extern library`](#extern-and-extern-library)
|
|
- [Valid scopes for `extern`](#valid-scopes-for-extern)
|
|
- [Effect on indirect imports](#effect-on-indirect-imports)
|
|
- [Indirect imports of non-`extern` types](#indirect-imports-of-non-extern-types)
|
|
- [Using imported declarations](#using-imported-declarations)
|
|
- [Validation for non-owning `extern library` declarations](#validation-for-non-owning-extern-library-declarations)
|
|
- [Alternatives considered](#alternatives-considered)
|
|
- [References](#references)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## Overview
|
|
|
|
Entities may have up to four declarations:
|
|
|
|
- An optional, owning forward declaration.
|
|
- For example, `class MyClass;`.
|
|
- This must come before the definition. The API file is considered to be
|
|
before the implementation file.
|
|
- A required, owning definition.
|
|
- For example, `class MyClass { ... }`.
|
|
- The definition might be the _only_ declaration.
|
|
- An optional, owning declaration in a `match_first` block.
|
|
- This only applies to `impl` declarations.
|
|
- This must be in the same file as the first owning declaration.
|
|
- An optional, non-owning `extern library "<owning_library>"` declaration.
|
|
- For example, `extern library "OtherLibrary" class MyClass;`.
|
|
- It must be in a separate library from the definition.
|
|
- The owning library's API file must import the `extern` declaration, and
|
|
must also contain a declaration.
|
|
- The owning library's declarations must have the `extern` modifier
|
|
(without `library`).
|
|
- For example, `extern class MyClass;`.
|
|
|
|
For example, a library can have a forward declaration of an entity in the API
|
|
file, and use the implementation file for the entity's definition. Putting the
|
|
definition in an implementation file this way can reduce the dependencies for
|
|
API file evaluation, improving compile time. This is commonly done with
|
|
functions. For example:
|
|
|
|
```
|
|
library "MyLibrary";
|
|
|
|
fn DoSomething();
|
|
```
|
|
|
|
```
|
|
impl library "MyLibrary";
|
|
|
|
fn DoSomething() {
|
|
...
|
|
}
|
|
```
|
|
|
|
An `impl` may appear in at most one `match_first` block, and only once within
|
|
it. A declaration in a `match_first` block may be the forward declaration or the
|
|
definition. It may also be a fourth declaration that is neither, and which is
|
|
only allowed to exist within such a block.
|
|
|
|
## Matching redeclarations of an entity
|
|
|
|
In order to determine whether two redeclarations refer to the same entity, we
|
|
apply the rules:
|
|
|
|
- Two named declarations _declare the same entity_ if they have the same scope
|
|
and the same name. This includes imported declarations.
|
|
- When two named declarations declare the same entity, the second is said to
|
|
be a _redeclaration_.
|
|
- Two owned declarations _differ_ if they don't syntactically match.
|
|
- Otherwise, if one is a non-owned `extern library` declaration,
|
|
declarations differ if they don't match semantically.
|
|
- The program is invalid if it contains two declarations of the same entity
|
|
that differ.
|
|
|
|
```carbon
|
|
class A {
|
|
// This function will be redeclared in order to provide a definition.
|
|
fn F(n: i32);
|
|
}
|
|
|
|
// ✅ Valid: The declaration matches syntactically.
|
|
fn A.F(n: i32) {}
|
|
|
|
// ❌ Invalid: The parameter name differs.
|
|
fn A.F(m: i32) {}
|
|
|
|
// ❌ Invalid: The parameter type differs syntactically.
|
|
fn A.F(n: (i32)) {}
|
|
```
|
|
|
|
### Details
|
|
|
|
#### Modifier keywords
|
|
|
|
As a rule of thumb, modifier keywords are required when, if prior optional
|
|
declarations were removed, the lack of the modifier keyword would change
|
|
behavior.
|
|
|
|
- `extend` in `extend impl` is only on the declaration in the class body
|
|
(whether that is a forward declaration or definition).
|
|
- Class and interface modifiers other than `extend` (`abstract`, `base`,
|
|
`final`) exist only on the definition, not on the forward declaration.
|
|
- Function modifiers (`override`, `virtual`, `default`, `abstract`, `final`)
|
|
must match between forward declaration and definition (though `abstract`
|
|
functions won't have definitions).
|
|
- If any owning declaration has the `extern` modifier, all owning declarations
|
|
must have it.
|
|
- Access modifiers (`private` and `protected`) must match across all
|
|
declarations and definitions, including between an `extern library
|
|
"<owning_library>"` declaration and the owning `extern` declaration.
|
|
|
|
> References:
|
|
>
|
|
> - ["Modifier keywords" in proposal #3762](/proposals/p003762-merging-forward-declarations.md#modifier-keywords)
|
|
> - [Proposal #3980: "Singular `extern` declarations"](/proposals/p003980-singular-extern-declarations.md#proposal)
|
|
|
|
#### Syntactic matching and scopes
|
|
|
|
Two owned declarations _syntactically match_ if the sequence of tokens in
|
|
the declaration following the introducer keyword and the optional scope, up
|
|
to the semicolon or open brace, is identical, except for `unused` modifiers
|
|
on parameters.
|
|
|
|
An entity may be redeclaration in a different scope using a qualified
|
|
declaration:
|
|
|
|
- Take the portion of the declaration from the introducer up to the end of
|
|
the scope.
|
|
- Replace the introducer keyword with the introducer keyword of the scope.
|
|
- Replace the trailing `.` with a `;`.
|
|
- The result must be a valid declaration of the scope, ignoring
|
|
restrictions on how often the scope can be redeclared.
|
|
|
|
Put another way: each portion of the qualified name must not differ from the
|
|
declaration of the corresponding entity.
|
|
|
|
For example:
|
|
|
|
```carbon
|
|
namespace N;
|
|
|
|
class N.C(T:! type) {
|
|
class D(U:! type) {
|
|
fn F(a: T, b: U);
|
|
}
|
|
}
|
|
|
|
fn N.C(T:! type).D(U:! type).F(a: T, b: U) {}
|
|
```
|
|
|
|
In this function definition:
|
|
|
|
- `F(a: T, b: U)` does not differ from the declaration of `F`.
|
|
- `class N.C(T:! type).D(U:! type);` would be a valid redeclaration of `D`,
|
|
because:
|
|
- `D(U:! type)` does not differ from the declaration of `D`.
|
|
- `class N.C(T:! type);` would be a valid redeclaration of `C`, because:
|
|
- `C(T:! type)` does not differ from the declaration of `C`.
|
|
- `namespace N;` would be a valid redeclaration of `N`.
|
|
|
|
So this is a valid definition of `F`.
|
|
|
|
Note that this means that, for example, all members of a class must use the same
|
|
name for each generic parameter of that class. It cannot be `T` in one
|
|
out-of-line member definition and `ElementType` in another, or the scope in the
|
|
out-of-line definition would not match.
|
|
|
|
To redeclare an `impl` after the end of the `class` scope it was declared
|
|
in, that scope may be re-entered as part of the `impl` redeclaration, in the
|
|
same way, except with parentheses around the name of the `impl`, as in
|
|
`impl X.(as Y) { ... }`.
|
|
See
|
|
["Declaring implementations" in the "Generics: details" design document](generics/details.md#declaring-implementations).
|
|
|
|
The members of an `impl` are not required to syntactically match the
|
|
corresponding members of the interface they are implementing since:
|
|
|
|
- We don't want to syntactically couple declarations that could be
|
|
in different libraries or packages. Such coupling would make refactorings
|
|
that change the way that code is expressed but not its meaning either
|
|
difficult or impossible.
|
|
- The associated function in an `impl` is expected to have different syntax
|
|
than that in the interface in some cases. The two declarations are in
|
|
different scopes, so will refer to the same types in different ways. And the
|
|
declaration in the `impl` is declared with knowledge of the `Self` type and
|
|
associated constants for the interface, which we allow to be used
|
|
directly in the declaration of the function.
|
|
|
|
See
|
|
["`impl` members vs `interface` members" in the "Generics: details" design document](generics/details.md#impl-members-vs-interface-members).
|
|
|
|
For `let` and `var` declarations with a single name binding
|
|
(`let Scope.A: Type = Value;`), the end of the declaration is at the `=` or
|
|
`;` rather than at the `}` or `;`. Note though it is an open question
|
|
whether this form permits redeclarations. An arbitrary pattern that is not a
|
|
single binding (`let (A: Type1, B: Type2) = Value;`) does not permit
|
|
redeclarations.
|
|
|
|
Any unqualified names used in syntactic matching will resolve to the same entity
|
|
in redeclarations due to the poisoning of failed unqualified lookups.
|
|
See
|
|
["Unqualified name lookup" in the "Name lookup" design document](name_lookup.md#unqualified-name-lookup).
|
|
|
|
> References:
|
|
>
|
|
> - [Proposal #3763: "Matching redeclarations"](/proposals/p003763-matching-redeclarations.md#proposal),
|
|
> including sections:
|
|
> - ["Scope differences"](/proposals/p003763-matching-redeclarations.md#scope-differences)
|
|
> - ["`let` and `var` declarations"](/proposals/p003763-matching-redeclarations.md#let-and-var-declarations)
|
|
> - ["Unqualified name lookup"](/proposals/p003763-matching-redeclarations.md#unqualified-name-lookup)
|
|
> - ["Declarations" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#declarations)
|
|
> - [Proposal #5366: "The name of an `impl` in `class` scope"](/proposals/p005366-the-name-of-an-impl-in-class-scope.md#proposal)
|
|
|
|
## `extern` and `extern library`
|
|
|
|
There are two forms of the `extern` modifier:
|
|
|
|
- On an owning declaration, `extern` limits access to the definition.
|
|
- The entity must be directly imported in order to use the definition;
|
|
otherwise it is incomplete.
|
|
- An `extern library` declaration is optional.
|
|
- Like all owning declarations, owning `extern` declarations use syntactic
|
|
matching for redeclarations.
|
|
- On a non-owning declaration, `extern library` allows references to an entity
|
|
without depending on the owning library.
|
|
- The library name indicates where the entity is defined.
|
|
- This can be used to improve build performance, such as by splitting out
|
|
a declaration in order to reduce a library's dependencies.
|
|
- `extern library` declarations only use semantic matching for
|
|
redeclarations, not syntactic matching.
|
|
|
|
For example, a use of both might look like:
|
|
|
|
```
|
|
library "owner";
|
|
|
|
// This `import` is required due to the `extern library`, but we also make use
|
|
// of `MyClassFactory` below. This is a circular use of `MyClass` that we
|
|
// couldn't split between libraries without `extern`.
|
|
import library "factory";
|
|
|
|
extern class MyClass {
|
|
fn Make() -> MyClass* {
|
|
return MyClassFactory();
|
|
}
|
|
|
|
var val: i32 = 0;
|
|
}
|
|
```
|
|
|
|
```
|
|
library "factory";
|
|
|
|
// Declares `MyClass` so that `MyClassFactory` can return it.
|
|
extern library "owner" class MyClass;
|
|
|
|
fn MyClassFactory(val: i32) -> MyClass*;
|
|
```
|
|
|
|
```
|
|
impl library "factory";
|
|
|
|
// Imports the definition of `MyClass`.
|
|
import library "owner";
|
|
|
|
extern fn MyClassFactory(val: i32) -> MyClass* {
|
|
var c: MyClass* = new MyClass();
|
|
c->val = val;
|
|
return c;
|
|
}
|
|
```
|
|
|
|
> References:
|
|
>
|
|
> - ["Impact on indirect imports" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#impact-on-indirect-imports)
|
|
> - ["No syntactic matching for `extern library` declarations" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#no-syntactic-matching-for-extern-library-declarations)
|
|
|
|
### Valid scopes for `extern`
|
|
|
|
The `extern` modifier is only valid on namespace-scoped entities, including in
|
|
the file scope. In other words, `class C { extern fn F(); }` is invalid.
|
|
|
|
### Effect on indirect imports
|
|
|
|
Indirect imports won't see the definition of an `extern` entity. We expect this
|
|
to primarily affect return types of functions. If an incomplete type is
|
|
encountered this way, it can be resolved by directly importing the definition.
|
|
For example:
|
|
|
|
```
|
|
library "type";
|
|
|
|
// Because this is `extern`, the definition must be directly imported.
|
|
extern class MyType { var x: i32 }
|
|
```
|
|
|
|
```
|
|
library "make_type";
|
|
|
|
import library "type";
|
|
|
|
// Here we have a function which returns the type.
|
|
fn MakeMyType() -> MyType*;
|
|
```
|
|
|
|
```
|
|
library "invalid_use";
|
|
|
|
import library "make_type";
|
|
|
|
fn InvalidUse() -> i32 {
|
|
// ❌ Invalid: `MyType` is incomplete because it's `extern` and not directly
|
|
// imported. `x` cannot be accessed.
|
|
return MakeMyType()->x;
|
|
}
|
|
```
|
|
|
|
```
|
|
library "valid_use";
|
|
|
|
import library "make_type";
|
|
|
|
// ✅ Valid: By directly importing the definition, we can now access `x`.
|
|
import library "type";
|
|
|
|
fn ValidUse() -> i32 {
|
|
return MakeMyType()->x;
|
|
}
|
|
```
|
|
|
|
#### Indirect imports of non-`extern` types
|
|
|
|
Non-`extern` entities are complete if their definition is imported, even if that
|
|
import is indirect, as in:
|
|
|
|
```
|
|
library "a";
|
|
|
|
class C { fn F(); }
|
|
```
|
|
|
|
```
|
|
library "b";
|
|
import library "a";
|
|
|
|
fn G() -> C;
|
|
```
|
|
|
|
```
|
|
library "c";
|
|
import library "b";
|
|
|
|
// Valid: `C` is complete here, even though it's not in name lookup.
|
|
G().F();
|
|
```
|
|
|
|
> References:
|
|
>
|
|
> - ["Indirect imports of non-`extern` types" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#indirect-imports-of-non-extern-types)
|
|
|
|
### Using imported declarations
|
|
|
|
Since `extern library "a" class C;` must be imported by the owning library, we
|
|
allow uses of the imported name prior to its declaration within the same file.
|
|
This means the following works:
|
|
|
|
```
|
|
library "extern";
|
|
|
|
extern library "use_extern" class MyType;
|
|
```
|
|
|
|
```
|
|
library "use_extern";
|
|
import library "extern";
|
|
|
|
// Uses the `extern library` declaration.
|
|
fn Foo(val: MyType*);
|
|
|
|
extern class MyType {
|
|
fn Bar[ref self: Self]() { Foo(&self); }
|
|
}
|
|
```
|
|
|
|
> References:
|
|
>
|
|
> - ["Using imported declarations" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#using-imported-declarations)
|
|
|
|
### Validation for non-owning `extern library` declarations
|
|
|
|
We offer some validation that the library in `extern library` is correct, in the
|
|
sense of being the single non-owning library declaring that entity and naming
|
|
the single owning library. When the owning library is incorrect, it's very
|
|
likely to be detected in two cases:
|
|
|
|
- A compile-time error when the owning library imports the non-owning library,
|
|
when the owning declaration is evaluated.
|
|
- A link-time error as a fallback.
|
|
|
|
Other cases, such as when both libraries are independently imported, may or may
|
|
not be caught, dependent upon the cost of validation.
|
|
|
|
> References:
|
|
>
|
|
> - ["Validation for non-owning `extern library` declarations" in proposal #3980](/proposals/p003980-singular-extern-declarations.md#validation-for-non-owning-extern-library-declarations)
|
|
|
|
## Alternatives considered
|
|
|
|
- [Other modifier keyword merging approaches](/proposals/p003762-merging-forward-declarations.md#other-modifier-keyword-merging-approaches)
|
|
- [No `extern` keyword](/proposals/p003762-merging-forward-declarations.md#no-extern-keyword)
|
|
- [Looser restrictions on declarations](/proposals/p003762-merging-forward-declarations.md#looser-restrictions-on-declarations)
|
|
- [`extern` naming](/proposals/p003762-merging-forward-declarations.md#extern-naming)
|
|
- [Default `extern` to private](/proposals/p003762-merging-forward-declarations.md#default-extern-to-private)
|
|
- [Opaque types](/proposals/p003762-merging-forward-declarations.md#opaque-types)
|
|
- [Require a library provide its own `extern` declarations](/proposals/p003762-merging-forward-declarations.md#require-a-library-provide-its-own-extern-declarations)
|
|
- [Allow cross-package `extern` declarations](/proposals/p003762-merging-forward-declarations.md#allow-cross-package-extern-declarations)
|
|
- [Use a partially or fully semantic rule](/proposals/p003763-matching-redeclarations.md#use-a-partially-or-fully-semantic-rule)
|
|
- [Use package-wide name poisoning](/proposals/p003763-matching-redeclarations.md#use-package-wide-name-poisoning)
|
|
- [Allow shadowing in implementation file after use in API file](/proposals/p003763-matching-redeclarations.md#allow-shadowing-in-implementation-file-after-use-in-api-file)
|
|
- [Allow multiple non-owning declarations, remove the import requirement, or both](/proposals/p003980-singular-extern-declarations.md#allow-multiple-non-owning-declarations-remove-the-import-requirement-or-both)
|
|
- [Total number of allowed declarations (owning and non-owning)](/proposals/p003980-singular-extern-declarations.md#total-number-of-allowed-declarations-owning-and-non-owning)
|
|
- [Do not restrict the number of forward declarations](/proposals/p003980-singular-extern-declarations.md#do-not-restrict-the-number-of-forward-declarations)
|
|
- [Allow up to two declarations total](/proposals/p003980-singular-extern-declarations.md#allow-up-to-two-declarations-total)
|
|
- [Allow up to four declarations total](/proposals/p003980-singular-extern-declarations.md#allow-up-to-four-declarations-total)
|
|
- [Don't require a modifier on the owning declarations](/proposals/p003980-singular-extern-declarations.md#dont-require-a-modifier-on-the-owning-declarations)
|
|
- [Only require `extern` on the first owning declaration](/proposals/p003980-singular-extern-declarations.md#only-require-extern-on-the-first-owning-declaration)
|
|
- [Separate require-direct-import from non-owning declarations](/proposals/p003980-singular-extern-declarations.md#separate-require-direct-import-from-non-owning-declarations)
|
|
- [Other `extern` syntaxes](/proposals/p003980-singular-extern-declarations.md#other-extern-syntaxes)
|
|
- [Have types with `extern` members re-export them](/proposals/p003980-singular-extern-declarations.md#have-types-with-extern-members-re-export-them)
|
|
- [Require syntactic matching for `extern library` declarations](/proposals/p003980-singular-extern-declarations.md#require-syntactic-matching-for-extern-library-declarations)
|
|
- [Use semantic match for the scope](/proposals/p005366-the-name-of-an-impl-in-class-scope.md#use-semantic-match-for-the-scope)
|
|
|
|
## References
|
|
|
|
- Proposal
|
|
[#3762: Merging forward declarations](https://github.com/carbon-language/carbon-lang/pull/3762)
|
|
- Proposal
|
|
[#3763: Matching redeclarations](https://github.com/carbon-language/carbon-lang/pull/3763)
|
|
- Proposal
|
|
[#3980: Singular `extern` declarations](https://github.com/carbon-language/carbon-lang/pull/3980)
|
|
- Proposal
|
|
[#5337: Interface extension and `final impl` update](https://github.com/carbon-language/carbon-lang/pull/5337)
|
|
- Proposal
|
|
[#5366: The name of an `impl` in `class` scope](https://github.com/carbon-language/carbon-lang/pull/5366)
|
|
- Proposal
|
|
[#7493: Disallow impl in match_first twice](https://github.com/carbon-language/carbon-lang/pull/7493)
|