"borrow checker invariants" section of the "leveraging the type system" chapter #2867

tall-vase · 2025-09-01T16:19:59Z

Adds materials on the "leveraging the type system/borrow checker invariants" subject.

I'm still calibrating what's expected subject-and-style wise, so do spell out things where I've drifted off mark.

…n to lifetime connections

google-cla · 2025-09-01T16:20:03Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/lifetime-connections.md

… are commented out.

djmitche

I apologize for the enormous delay here -- it's been a busy couple of months!

This looks great, and I appreciate seeing previous comments included here.

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/lifetime-connections.md

gribozavr

First pass, generally looking good, but I left some comments that may lead to structural changes, so I expect to do another detailed pass after you land some changes.

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md

gribozavr · 2025-10-05T17:54:03Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md

@@ -0,0 +1,80 @@
+---
+minutes: 0


Please add the timing information.

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

gribozavr · 2025-10-05T17:59:04Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+
+- By keeping constructors private and not implementing clone/copy for a type,
+  making the interior type opaque (as per the newtype pattern), we can prevent
+  multiple uses of the same, API-controlled value.


Not clear what "API-controlled" means here.

gribozavr · 2025-10-05T18:07:21Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

+    do_something_with_transaction(transaction);
+    let assumed_the_transactions_happened_immediately = db.results(); // ❌🔨
+    do_something_with_transaction(transaction);
+    // Works, as the lifetime of "transaction" as a reference ended above.


I might be misunderstanding your intent behind this example, but it does not feel realistic realistic because the database didn't get a notification that the borrow has ended, and thus could not have started executing it. In other words, it is not clear what the DatabaseConnection type achieved by being locked out while the transaction was borrowed out.

Maybe you can fix it by wrapping the reference in a custom wrapper type which implements Drop? Ideally, that drop() would also print a message (like "executing query...") to make it clear to the audience that the database can indeed fill in the result list.

gribozavr · 2025-10-08T14:07:45Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/lifetime-connections.md

+
+# Lifetime "Connections" & External Resources
+
+Using `PhantomData` in conjunction with lifetimes lets us say "this value may


This made me think, do we have a slide on PhantomData, just about the concept by itself? Should we have one?

It seems like there are a few things to say to motivate PhantomData's existence (that is, before we even introduce it on the slide), in particular that the compiler infers certain properties of a user-defined type based on its fields - this would be surprising to many people, I think.

We do not. Prior to starting work on this chapter there wasn't a mention of PhantomData in the repository at all.

If there's a place for it to exist, it's likely in a revision on the typestate work. I'll pull together something short that can slot in just before the lifetime-connections slide for now under the assumption it can be moved about as needed.

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

gribozavr · 2025-10-08T14:25:16Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

+  majority of them. See:
+  [Lifetime Elision](../../../lifetimes/lifetime-elision.md).
+
+</details>


This slide might be a place where an analogy might help some listeners understand what we are trying to get at when we say that the borrow checker and lifetimes are just another API design tool. Here's one possible analogy. WDYT?

Generics in Java were added primarily to support type-safe collections. In fact, Java 5 added generic type arguments to existing standard library collection types that were previously non-generic! So the language designers had a clear primary use case in mind. However, generics turned out to be useful in many other API designs. So it would be too narrow-minded to present Java generics as "a language feature for type-safe collections."

Similarly, the lifetimes and the borrow checker were introduced in Rust for compile-time memory safety guarantees, but their applicability in API design is broader. We (the Rust community) are still discovering design patterns and trying to understand what these tools can do for API design beyond memory safety.

Seems like a good thing to bring up, I'll pull together some references to drop in. If you've got suggestions on pieces covering this I'd be happy to hear about them, but I understand linkrot and the ephemeral nature of back-channel discussion of the time may have gotten to most of it.

JSR 14 which introduced generics lists only one goal specific to a use case, and it is "Good collections support. The core Collections APIs and similar APIs are perhaps the most important customers of genericity, so it is essential that they work well as, and with, generic classes." Furthermore, this is the #1 goal of the proposal overall.

An empirical research article that I could find, Java generics adoption: how new features are introduced, championed, or ignored studies how generics were adopted in practice. It includes a data-driven argument that the most common parameterized types are collections (the only non-collection-related type in Table 1 is Class<?>). This aligns with my intuition: the primary use case is collections, but there are other cases where generics turned out to be useful (for example, Class<?> in the standard library, TypeToken<?> in Google's Guava to work around type erasure in Java's generics, or the "recursive generics" pattern similar to CRTP in C++).

One source that I had high hopes for, ACM's History of programming languages journal, unfortunately does have a piece on Java.

Wonderful, thank you!

Co-authored-by: Dmitri Gribenko <[email protected]>

gribozavr · 2025-10-10T16:04:55Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

+        &self.query_results
+    }
+    pub fn commit(&mut self) {
+        /* Work omitted, including sending/clearing the transaction */


Suggested change

/* Work omitted, including sending/clearing the transaction */

// Work omitted, including sending/clearing the transaction

gribozavr · 2025-10-10T16:06:15Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+```rust,editable
+mod cryptography {
+    pub struct Key(/* specifics omitted */);
+    // Pretend this is a cryptographically sound, single-use number.


Suggested change

// Pretend this is a cryptographically sound, single-use number.

// A single-use number suitable for cryptographic purposes.

gribozavr · 2025-10-10T16:06:25Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+    pub struct Key(/* specifics omitted */);
+    // Pretend this is a cryptographically sound, single-use number.
+    pub struct Nonce(u32);
+    // And pretend this is cryptographically sound random generator function.


Suggested change

// And pretend this is cryptographically sound random generator function.

// A cryptographically sound random generator function.

gribozavr · 2025-10-10T16:07:06Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+    pub struct Nonce(u32);
+    // And pretend this is cryptographically sound random generator function.
+    pub fn new_nonce() -> Nonce {
+        Nonce(std::time::UNIX_EPOCH.elapsed().unwrap_or_default().subsec_nanos())


Suggested change

Nonce(std::time::UNIX_EPOCH.elapsed().unwrap_or_default().subsec_nanos())

Nonce(4) // chosen by a fair dice roll, https://xkcd.com/221/

The timestamp was not a good RNG anyway, and showing a good one is not the point of the example. With a bit of lighthearted humor we can telegraph that this is a pretend-RNG.

gribozavr · 2025-10-10T16:07:28Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+        Nonce(std::time::UNIX_EPOCH.elapsed().unwrap_or_default().subsec_nanos())
+    }
+
+    // We consume a nonce, but not the key or the data.


Suggested change

// We consume a nonce, but not the key or the data.

// Consume a nonce, but not the key or the data.

gribozavr · 2025-10-10T16:07:52Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md

+}
+
+use cryptography::*;


Suggested change

}

use cryptography::*;

gribozavr · 2025-10-10T16:14:08Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

+- When a new feature is introduced to users, it is often done so with a specific
+  idea of what it will be used for.


Suggested change

- When a new feature is introduced to users, it is often done so with a specific

idea of what it will be used for.

- Language features are often introduced for a specific purpose.

gribozavr · 2025-10-10T16:14:27Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

+  not been foreseen.
+
+  In 2004, Java 5 introduced Generics with the
+  [main stated purpose of enabling type safe collections](https://jcp.org/en/jsr/detail?id=14).


Suggested change

[main stated purpose of enabling type safe collections](https://jcp.org/en/jsr/detail?id=14).

[main stated purpose of enabling type-safe collections](https://jcp.org/en/jsr/detail?id=14).

gribozavr · 2025-10-10T16:14:39Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

+  [main stated purpose of enabling type safe collections](https://jcp.org/en/jsr/detail?id=14).
+
+  Since then, users and developers of the language expanded the use of generics
+  to other areas of type safe API design.


Suggested change

to other areas of type safe API design.

to other areas of type-safe API design.

gribozavr · 2025-10-10T16:16:26Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md

+  What we aim to do here is similar: The borrow checker, after being introduced
+  to people with the purpose of avoiding use-after-free and data races, is being
+  used to model things that have nothing to do with preventing those classes of
+  misuse.


Suggested change

What we aim to do here is similar: The borrow checker, after being introduced

to people with the purpose of avoiding use-after-free and data races, is being

used to model things that have nothing to do with preventing those classes of

misuse.

What we aim to do here is similar: Even though the borrow checker was introduced

to prevent use-after-free and data races, it is just another API design tool. It can be

used to model program properties that have nothing to do with preventing memory safety bugs.

gribozavr · 2025-10-10T16:18:49Z

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md

+  exclusive reference we prevent access to the other fields of that struct under
+  a shared / non-exclusive reference until the lifetime of that borrow ends.
+
+  Note: This has to be via a method, as the compiler can reason about borrowing


Suggested change

Note: This has to be via a method, as the compiler can reason about borrowing

- The `transaction` field must be borrowed via a method, as the compiler can reason about borrowing

This is a major part (esp. since now there's a demonstration), so it deserves a top-level bullet point.

tall-vase added 5 commits August 27, 2025 16:07

Initial draft of the 'borrow checker invariants' section

b771e7f

Elaborate more on the cryptography example

3831858

Begin expanding the slide notes, rename the external resources sectio…

a81b55a

…n to lifetime connections

Get this section into a 'review ready' state.

0b4318f

Reset all minutes on the borrowck invariants section to 0

728af30

tall-vase added the deep_dives/idiomatic label Sep 1, 2025

tall-vase changed the title ~~"borrow checker invariants" section of the~~ "borrow checker invariants" section of the "leveraging the type system" chapter Sep 1, 2025

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants.md Outdated Show resolved Hide resolved

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md Show resolved Hide resolved

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/generalizing-ownership.md Outdated Show resolved Hide resolved

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/single-use-values.md Show resolved Hide resolved

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md Outdated Show resolved Hide resolved

LukeMathWalker reviewed Sep 2, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md Outdated Show resolved Hide resolved

LukeMathWalker reviewed Sep 3, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/aliasing-xor-mutability.md Outdated Show resolved Hide resolved

djmitche reviewed Sep 6, 2025

View reviewed changes

tall-vase added 5 commits September 8, 2025 16:30

General editing pass based off feedback

a37a272

Minor editing

88852f2

Another editing pass

0aa4f21

minor grammar edit

37e69fe

Another editing pass

595ca8e

tall-vase requested review from LukeMathWalker and djmitche September 19, 2025 12:51

gribozavr requested review from gribozavr and removed request for LukeMathWalker September 21, 2025 22:56

tall-vase and others added 5 commits September 22, 2025 11:47

Formatting pass

2a88748

Merge branch 'main' into idiomatic/typesystem-borrowchecker

31284d6

fix test errors, make sure compilation succeeds after erroneous lines…

e7f874b

… are commented out.

Address lints

808de4f

Address lints

85b70f0

djmitche approved these changes Sep 27, 2025

View reviewed changes

src/idiomatic/leveraging-the-type-system/borrow-checker-invariants/lifetime-connections.md Outdated Show resolved Hide resolved

gribozavr self-assigned this Oct 3, 2025

gribozavr reviewed Oct 8, 2025

View reviewed changes

gribozavr assigned tall-vase and unassigned gribozavr Oct 8, 2025

gribozavr added the waiting for author Waiting on the issue author to reply label Oct 8, 2025

tall-vase and others added 4 commits October 10, 2025 09:09

Apply suggestions from code review

44dff2a

Co-authored-by: Dmitri Gribenko <[email protected]>

Partially address feedback

ebf00a2

Add TODO

7b72587

Formatting pass

9f49ba5

gribozavr reviewed Oct 10, 2025

View reviewed changes


		# Lifetime "Connections" & External Resources

		Using `PhantomData` in conjunction with lifetimes lets us say "this value may

	/* Work omitted, including sending/clearing the transaction */
	// Work omitted, including sending/clearing the transaction

	// Pretend this is a cryptographically sound, single-use number.
	// A single-use number suitable for cryptographic purposes.

	// And pretend this is cryptographically sound random generator function.
	// A cryptographically sound random generator function.

	Nonce(std::time::UNIX_EPOCH.elapsed().unwrap_or_default().subsec_nanos())
	Nonce(4) // chosen by a fair dice roll, https://xkcd.com/221/

	// We consume a nonce, but not the key or the data.
	// Consume a nonce, but not the key or the data.

		- When a new feature is introduced to users, it is often done so with a specific
		idea of what it will be used for.

	- When a new feature is introduced to users, it is often done so with a specific
	idea of what it will be used for.
	- Language features are often introduced for a specific purpose.

	[main stated purpose of enabling type safe collections](https://jcp.org/en/jsr/detail?id=14).
	[main stated purpose of enabling type-safe collections](https://jcp.org/en/jsr/detail?id=14).

	to other areas of type safe API design.
	to other areas of type-safe API design.

		@@ -0,0 +1,80 @@
		---
		minutes: 0

	Note: This has to be via a method, as the compiler can reason about borrowing
	- The `transaction` field must be borrowed via a method, as the compiler can reason about borrowing

"borrow checker invariants" section of the "leveraging the type system" chapter #2867

Are you sure you want to change the base?

"borrow checker invariants" section of the "leveraging the type system" chapter #2867

Uh oh!

Conversation

tall-vase commented Sep 1, 2025

Uh oh!

google-cla bot commented Sep 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

djmitche left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gribozavr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gribozavr Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gribozavr Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gribozavr Oct 10, 2025 •

edited

Loading

gribozavr Oct 10, 2025 •

edited

Loading