Skip to content

Commit

Permalink
Rename "partial facet" and to "partial class type" (#4402)
Browse files Browse the repository at this point in the history
See [2024-10-01 discussion on #typesystem in
Discord](https://discord.com/channels/655572317891461132/708431657849585705/1290774105498325122).

Co-authored-by: Josh L <[email protected]>
  • Loading branch information
josh11b and josh11b authored Oct 11, 2024
1 parent 851ef2c commit b0cde70
Showing 1 changed file with 20 additions and 18 deletions.
38 changes: 20 additions & 18 deletions docs/design/classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
- [Subtyping](#subtyping)
- [`Self` refers to the current type](#self-refers-to-the-current-type)
- [Constructors](#constructors)
- [Partial facet](#partial-facet)
- [Partial class type](#partial-class-type)
- [Usage](#usage)
- [Assignment with inheritance](#assignment-with-inheritance)
- [Destructors](#destructors)
Expand Down Expand Up @@ -1350,17 +1350,17 @@ There are two cases that aren't well supported with this pattern:

While expected to be relatively rarely needed, we will address both of these
concerns with a specialized type just used during construction of base classes,
called the partial facet type for the class.
called the partial class type for the class.

##### Partial facet
##### Partial class type

The partial facet for a base class type like `MyBaseType` is written
The partial class type for a base class type like `MyBaseType` is written
`partial MyBaseType`.

- Only methods that take the partial facet type may be called on the partial
facet type, so methods have to opt in to being called on an object that
- Only methods that take the partial class type may be called on the partial
class type, so methods have to opt in to being called on an object that
isn't fully constructed.
- No virtual methods may take the partial facet type, so there is no way to
- No virtual methods may take the partial class type, so there is no way to
transitively call a virtual method on an object that isn't fully
constructed.
- `partial MyBaseClass` and `MyBaseClass` have the same fields in the same
Expand Down Expand Up @@ -1392,7 +1392,7 @@ The partial facet for a base class type like `MyBaseType` is written
##### Usage

The general pattern is that base classes can define constructors returning the
partial facet type.
partial class type.

```
base class MyBaseClass {
Expand All @@ -1403,7 +1403,7 @@ base class MyBaseClass {
}
```

Extensible classes can be instantiated even from a partial facet value:
Extensible classes can be instantiated even from a partial class type value:

```
var mbc: MyBaseClass = MyBaseClass.Make();
Expand All @@ -1413,9 +1413,10 @@ The conversion from `partial MyBaseClass` to `MyBaseClass` only fills in the
vptr value and can be done in place. After the conversion, all public methods
may be called, including virtual methods.

The partial facet is required for abstract classes, since otherwise they may not
be instantiated. Constructor functions for abstract classes should be marked
[protected](#protected-access) so they may only be accessed in derived classes.
The partial class type is required for abstract classes, since otherwise they
may not be instantiated. Constructor functions for abstract classes should be
marked [protected](#protected-access) so they may only be accessed in derived
classes.

```
abstract class MyAbstractClass {
Expand All @@ -1431,7 +1432,8 @@ var abc: MyAbstractClass = ...;
If a base class wants to store a pointer to itself somewhere in the constructor
function, there are two choices:

- An extensible class could use the plain type instead of the partial facet.
- An extensible class could use the plain type instead of the partial class
type.

```
base class MyBaseClass {
Expand All @@ -1458,8 +1460,8 @@ function, there are two choices:
}
```

The constructor for a derived class may construct values from a partial facet of
the class' immediate base type or the full type:
The constructor for a derived class may construct values from a partial class
type of the class' immediate base type or the full type:

```
abstract class MyAbstractClass {
Expand Down Expand Up @@ -1489,7 +1491,7 @@ base class ExtensibleDerived {
}
```

And final classes will return a type that does not use the partial facet:
And final classes will return a type that does not use the partial class type:

```
class FinalDerived {
Expand All @@ -1502,13 +1504,13 @@ class FinalDerived {
```

Observe that the vptr is only assigned twice in release builds if you use
partial facets:
partial class types:

- The first class value created, by the factory function creating the base of
the class hierarchy, initialized the vptr field to nullptr. Every derived
type transitively created from that value will leave it alone.
- Only when the value has its most-derived class and is converted from the
partial facet type to its final type is the vptr field set to its final
partial class type to its final type is the vptr field set to its final
value.

In the case that the base class can be instantiated, tooling could optionally
Expand Down

0 comments on commit b0cde70

Please sign in to comment.