NOTE: This article is currently under a rewrite with a new example.
Therefore it might not make much sense at places.
Please wait until I finish rewriting the article.

My thoughts on (and need for) partial borrows

I am a long time advocate for partial borrows.

Frustrated by Rust's lack of support for them, I keep bringing the topic up
on the Rust Discord server, annoying people, and never really achieving anything.

So in this post, I will try to collect all my thoughts on partial borrows, and stop pestering people with them once and for all.

To be exact, I will focus on methods, as I think they are by far the biggest use case for partial borrows, and what I always end up needing.

The problem

I have been suffering from methods borrowing every field for a long time.
It comes up a lot when I'm developing applications that have complex interactions between components.

Since I'm terrible at thinking up examples, I will show an example from one of my projects, a GUI hex editor with a lot of features.

My hex editor supports multiple configurable layouts, which can show different parts of a file in different ways.

To achieve this, I have a type that holds the information on how to display a binary file.

#[derive(Default)]
pub struct HexState {
    pub ui: HexUi,
    pub meta_state: MetaState,
}

It has two fields:

• meta_state, which holds meta-information about the data, like different layouts that can present the data in an easy to grasp way.
• ui, which holds the ui state, like which layout is active

Then, I have a method that switches the active layout:

impl HexState {
    pub(crate) fn switch_layout(&mut self, k: LayoutKey) {
        self.ui.current_layout = k;
        // Set focused view to the first available view in the layout
        if let Some(view_key) = self.meta_state.meta.layouts[k]
            .view_grid
            .get(0)
            .and_then(|row| row.get(0))
        {
            self.ui.focused_view = Some(*view_key);
        }
    }
}

So far so good.
Let's try to call it in a non-trivial context.
In the following code, I have a UI that presents a list of layouts, and if a layout in the list is clicked, that layout is set.

        for (k, v) in &app.hex.meta_state.meta.layouts {
            if ui.selectable_label(win.selected == k, &v.name).clicked() {
                win.selected = k;
                app.hex.switch_layout(k);
            }
        }

error[E0502]: cannot borrow `app.hex` as mutable because it is also borrowed as immutable
  --> src/gui/layouts_window.rs:32:17
   |
29 |         for (k, v) in &app.hex.meta_state.meta.layouts {
   |                       --------------------------------
   |                       |
   |                       immutable borrow occurs here
   |                       immutable borrow later used here
...
32 |                 app.hex.switch_layout(k);
   |                 ^^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here

The borrow checker cannot see that the switch_layout method only needs the layouts part of MetaState.

The solution

How do we solve the problem of a method call borrowing every field?
Well, the most obvious solution is not to borrow every field.

    for (k, v) in &app.meta_state.meta.layouts {
        if ui.selectable_label(win.selected == k, &v.name).clicked() {
            win.selected = k;
            App::switch_layout(&mut app.hex_ui, &app.meta_state.meta, k);
        }
    }

Problem solved, right?

Problems with the solution

What's so bad about this that it raises a need for partial borrows?
The short answer is that it makes the code less DRY.

Let's think about what properties makes methods so nice, and why this solution breaks them. I'll just call them the three nicenesses for lack of a better term:

Niceness 1: It's obvious which parameters belong to your type

With fn put_char(&mut self, ch: u8);, it's obvious that term wants mutable access to itself, in order to achieve whatever it wants with ch.

With fn put_char(cells: &mut Vec<u8>, width: &u16, height: &mut usize, cursor: &mut Cursor, ch: u8), it's not quite so obvious anymore.
Which one of these belong to Term, and which ones are the free parameters?
What if you call put_char with arguments that are not part of Term? There will be bugs, because put_char is designed to update the state of the Term itself.

Niceness 2: You don't have to repeat the types of your fields

With fn put_char(&mut self, ch: u8), you never have to redeclare the types of Term's fields.

With fn put_char(cells: &mut Vec<u8>, width: &u16, height: &mut usize, cursor: &mut Cursor, ch: u8), you have to specify all the types of your fields again. Now you have to keep in sync two (or more if you have multiple such methods) type annotations for your fields.
What if your field has a complex type, like field: &mut Option<Vec<Mutex<SomeOtherType>>>?
Type aliases help, but it should't be necessary to introduce a type alias because a single field has that type.

Niceness 3: Call site ergonomics

I think this one speaks for itself. Which one is more pleasant to write and read?

Self::put_char(
    &mut self.cells,
    &self.width,
    &mut self.height,
    &mut self.cursor,
    c,
)

vs.

self.put_char(c)

The former can build up fatigue quickly if the function is called in a lot of places.

The real solution: Partial borrowing methods

Can we have the best of both worlds? Have a method only borrow a chosen subset of fields, while retaining all the three nicenesses of methods?

This concept is called partial borrows.

Below, I'll try to give an example of one possible way it could look like, as well as detail some of the drawbacks and why such a design hasn't been accepted yet.

Partial borrowing method concept: self.field parameters

We could extend the self parameter syntax to allow borrowing individual fields, while expressing that these are fields of this type.

fn put_char(&mut self.cells, &self.width, &mut self.height, &mut self.cursor, ch: u8) {
    self.extend_while_cursor_past();
    self.cells[self.cursor.index(self.width)] = ch;
    self.cursor.x += 1;
    if self.cursor.x >= self.width {
        self.cursor.x = 0;
        self.cursor.y += 1;
    }
}

Calling it would be as simple as calling a normal &mut self method.

pub fn feed(&mut self, data: &[u8]) {
    self.ansi_parser.advance(data, |cmd| match cmd {
        TermCmd::PutChar(c) => self.put_char(c),
        _ => todo!()
    });
}

You may have noticed that we are calling a method inside put_char.
Don't worry, it's also using self.field parameters:

fn extend_while_cursor_past(&mut self.cells, &mut self.cursor, &self.width, &mut self.height) {
    while self.cursor.y >= self.height {
        self.extend();
    }
}

And so on:

fn extend(&mut self.cells, &self.width, &mut self.height) {
    self.cells.extend(std::iter::repeat(b' ').take(self.width as usize));
    self.height += 1;
}

This retains all the three nicenesses of methods:

1. Knowing which parameters are part of our type
2. Not having to repeat field type annotations
3. Being ergonomic to write/read at the call site.

Problems with partial borrows

Okay, cool. But if partial borrows are so great, how come an RFC wasn't accepted yet?

Unfortunately, partial borrows aren't all rainbows and sunshine either.

Here are some problems that I can currently recall:

New syntax

This one is kinda obvious, but complicating the grammar of the language needs a strong enough motivation. Are the benefits of partial borrows worth making the syntax more complex? My answer is a very strong yes.

Borrows become less obvious at a glance.

Normal function call:

Self::put_char(
    &mut self.cells,
    &self.width,
    &mut self.height,
    &mut self.cursor,
    c,
)

It is quite clear at a glance what fields this call borrows.

Partial method call:

self.put_char(c);

Is this a normal method or a partial method? What fields is it borrowing? For the answer, you have to look at the definition of put_char.

In my opinion, this is not a big enough problem, because the compiler will yell at you if you cause any borrow issues, like always.

What about diagnostics?
The compiler could easily expand a partial method call so that it's easy to show where a borrow conflict occurs.

self.put_char(c);

Diagnostic output:
self.put_char(
    &mut self.cells,
    &self.width,
    ^^^ The borrow conflict occurs here
    &mut self.height,
    &mut self.cursor,
    c,
)

The elephant in the room: Visibility and semver hazards

This is the most often brought up argument against partial borrows.

Private fields

What if we want to borrow a private field partially? If we put it in the signature of a partial method, its existence will be exposed to the public!
While this is not ideal, in my opinion it's better than the alternative of making the field public. While the existence of the field is now publicly known, read and write access still remains private, so invariants will not be broken by this. And by far the most important part of privacy is protecting invariants. Semver is secondary (in my opinion).
However, I do understand it is a semver hazard, and that's a valid problem to consider.
There are some alternate solutions being discussed, like "borrow regions" or "borrow groups" that would abstract away the existence of fields.

etc.

To be honest, I don't quite grasp all the semver arguments against partial borrows. Just know that it's the most common and strong argument against partial borrows.

If semver turns out to be an unsolvable problem (I hope not), I would be more than willing to accept partial borrows being restricted to intra-crate APIs, that is, APIs that are not reachable from outside of the current crate (think pub(crate)).
This would still solve 99% of my pain, which usually comes up when working on complex internals, and not when designing public APIs.

Conclusion

While this post doesn't propose a concrete design for partial borrows, I hope I have convinced enough people that this is a problem worth solving, and shouldn't be dismissed by telling people to restructure their code.

It is by far my biggest frustration with Rust, one that constantly sucks joy out of Rust programming for me.

I hope I'm not alone in feeling this way!

And I hope that if a solution does surface, it retains the three nicenesses of methods, as detailed above.

Thanks for bearing with me, and Happy Rusting!

Further reading:

• https://smallcultfollowing.com/babysteps//blog/2021/11/05/view-types/
• https://github.com/rust-lang/rfcs/issues/1215