## `Rc`, the Reference Counted Smart Pointer In the majority of cases, ownership is clear: you know exactly which variable owns a given value. However, there are cases when a single value might have multiple owners. For example, in graph data structures, multiple edges might point to the same node, and that node is conceptually owned by all of the edges that point to it. A node shouldn’t be cleaned up unless it doesn’t have any edges pointing to it. To enable multiple ownership, Rust has a type called `Rc`, which is an abbreviation for *reference counting*. The `Rc` type keeps track of the number of references to a value which determines whether or not a value is still in use. If there are zero references to a value, the value can be cleaned up without any references becoming invalid. Imagine `Rc` as a TV in a family room. When one person enters to watch TV, they turn it on. Others can come into the room and watch the TV. When the last person leaves the room, they turn off the TV because it’s no longer being used. If someone turns off the TV while others are still watching it, there would be uproar from the remaining TV watchers! We use the `Rc` type when we want to allocate some data on the heap for multiple parts of our program to read and we can’t determine at compile time which part will finish using the data last. If we knew which part would finish last, we could just make that part the data’s owner, and the normal ownership rules enforced at compile time would take effect. Note that `Rc` is only for use in single-threaded scenarios. When we discuss concurrency in Chapter 16, we’ll cover how to do reference counting in multithreaded programs. ### Using `Rc` to Share Data Let’s return to our cons list example in Listing 15-5. Recall that we defined it using `Box`. This time, we’ll create two lists that both share ownership of a third list. Conceptually, this looks similar to Figure 15-3: Figure 15-3: Two lists, `b` and `c`, sharing ownership of a third list, `a` We’ll create list `a` that contains 5 and then 10. Then we’ll make two more lists: `b` that starts with 3 and `c` that starts with 4. Both `b` and `c` lists will then continue on to the first `a` list containing 5 and 10. In other words, both lists will share the first list containing 5 and 10. Trying to implement this scenario using our definition of `List` with `Box` won’t work, as shown in Listing 15-17: Filename: src/main.rs ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-17/src/main.rs}} ``` Listing 15-17: Demonstrating we’re not allowed to have two lists using `Box` that try to share ownership of a third list When we compile this code, we get this error: ```console {{#include ../listings/ch15-smart-pointers/listing-15-17/output.txt}} ``` The `Cons` variants own the data they hold, so when we create the `b` list, `a` is moved into `b` and `b` owns `a`. Then, when we try to use `a` again when creating `c`, we’re not allowed to because `a` has been moved. We could change the definition of `Cons` to hold references instead, but then we would have to specify lifetime parameters. By specifying lifetime parameters, we would be specifying that every element in the list will live at least as long as the entire list. The borrow checker wouldn’t let us compile `let a = Cons(10, &Nil);` for example, because the temporary `Nil` value would be dropped before `a` could take a reference to it. Instead, we’ll change our definition of `List` to use `Rc` in place of `Box`, as shown in Listing 15-18. Each `Cons` variant will now hold a value and an `Rc` pointing to a `List`. When we create `b`, instead of taking ownership of `a`, we’ll clone the `Rc` that `a` is holding, thereby increasing the number of references from one to two and letting `a` and `b` share ownership of the data in that `Rc`. We’ll also clone `a` when creating `c`, increasing the number of references from two to three. Every time we call `Rc::clone`, the reference count to the data within the `Rc` will increase, and the data won’t be cleaned up unless there are zero references to it. Filename: src/main.rs ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-18/src/main.rs}} ``` Listing 15-18: A definition of `List` that uses `Rc` We need to add a `use` statement to bring `Rc` into scope because it’s not in the prelude. In `main`, we create the list holding 5 and 10 and store it in a new `Rc` in `a`. Then when we create `b` and `c`, we call the `Rc::clone` function and pass a reference to the `Rc` in `a` as an argument. We could have called `a.clone()` rather than `Rc::clone(&a)`, but Rust’s convention is to use `Rc::clone` in this case. The implementation of `Rc::clone` doesn’t make a deep copy of all the data like most types’ implementations of `clone` do. The call to `Rc::clone` only increments the reference count, which doesn’t take much time. Deep copies of data can take a lot of time. By using `Rc::clone` for reference counting, we can visually distinguish between the deep-copy kinds of clones and the kinds of clones that increase the reference count. When looking for performance problems in the code, we only need to consider the deep-copy clones and can disregard calls to `Rc::clone`. ### Cloning an `Rc` Increases the Reference Count Let’s change our working example in Listing 15-18 so we can see the reference counts changing as we create and drop references to the `Rc` in `a`. In Listing 15-19, we’ll change `main` so it has an inner scope around list `c`; then we can see how the reference count changes when `c` goes out of scope. Filename: src/main.rs ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-19/src/main.rs:here}} ``` Listing 15-19: Printing the reference count At each point in the program where the reference count changes, we print the reference count, which we can get by calling the `Rc::strong_count` function. This function is named `strong_count` rather than `count` because the `Rc` type also has a `weak_count`; we’ll see what `weak_count` is used for in the [“Preventing Reference Cycles: Turning an `Rc` into a `Weak`”][preventing-ref-cycles] section. This code prints the following: ```console {{#include ../listings/ch15-smart-pointers/listing-15-19/output.txt}} ``` We can see that the `Rc` in `a` has an initial reference count of 1; then each time we call `clone`, the count goes up by 1. When `c` goes out of scope, the count goes down by 1. We don’t have to call a function to decrease the reference count like we have to call `Rc::clone` to increase the reference count: the implementation of the `Drop` trait decreases the reference count automatically when an `Rc` value goes out of scope. What we can’t see in this example is that when `b` and then `a` go out of scope at the end of `main`, the count is then 0, and the `Rc` is cleaned up completely at that point. Using `Rc` allows a single value to have multiple owners, and the count ensures that the value remains valid as long as any of the owners still exist. Via immutable references, `Rc` allows you to share data between multiple parts of your program for reading only. If `Rc` allowed you to have multiple mutable references too, you might violate one of the borrowing rules discussed in Chapter 4: multiple mutable borrows to the same place can cause data races and inconsistencies. But being able to mutate data is very useful! In the next section, we’ll discuss the interior mutability pattern and the `RefCell` type that you can use in conjunction with an `Rc` to work with this immutability restriction. [preventing-ref-cycles]: ch15-06-reference-cycles.html#preventing-reference-cycles-turning-an-rct-into-a-weakt