<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>RefCell<T> and the Interior Mutability Pattern - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="foreword.html">Foreword</a></li><li class="affix"><a href="ch00-00-introduction.html">Introduction</a></li><li><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> How Functions Work</a></li><li><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References & Borrowing</a></li><li><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> Slices</a></li></ol></li><li><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li><a href="ch07-00-modules.html"><strong aria-hidden="true">7.</strong> Modules</a></li><li><ol class="section"><li><a href="ch07-01-mod-and-the-filesystem.html"><strong aria-hidden="true">7.1.</strong> mod and the Filesystem</a></li><li><a href="ch07-02-controlling-visibility-with-pub.html"><strong aria-hidden="true">7.2.</strong> Controlling Visibility with pub</a></li><li><a href="ch07-03-importing-names-with-use.html"><strong aria-hidden="true">7.3.</strong> Referring to Names in Different Modules</a></li></ol></li><li><a href="ch08-00-common-collections.html"><strong aria-hidden="true">8.</strong> Common Collections</a></li><li><ol class="section"><li><a href="ch08-01-vectors.html"><strong aria-hidden="true">8.1.</strong> Vectors</a></li><li><a href="ch08-02-strings.html"><strong aria-hidden="true">8.2.</strong> Strings</a></li><li><a href="ch08-03-hash-maps.html"><strong aria-hidden="true">8.3.</strong> Hash Maps</a></li></ol></li><li><a href="ch09-00-error-handling.html"><strong aria-hidden="true">9.</strong> Error Handling</a></li><li><ol class="section"><li><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong aria-hidden="true">9.1.</strong> Unrecoverable Errors with panic!</a></li><li><a href="ch09-02-recoverable-errors-with-result.html"><strong aria-hidden="true">9.2.</strong> Recoverable Errors with Result</a></li><li><a href="ch09-03-to-panic-or-not-to-panic.html"><strong aria-hidden="true">9.3.</strong> To panic! or Not To panic!</a></li></ol></li><li><a href="ch10-00-generics.html"><strong aria-hidden="true">10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ol class="section"><li><a href="ch10-01-syntax.html"><strong aria-hidden="true">10.1.</strong> Generic Data Types</a></li><li><a href="ch10-02-traits.html"><strong aria-hidden="true">10.2.</strong> Traits: Defining Shared Behavior</a></li><li><a href="ch10-03-lifetime-syntax.html"><strong aria-hidden="true">10.3.</strong> Validating References with Lifetimes</a></li></ol></li><li><a href="ch11-00-testing.html"><strong aria-hidden="true">11.</strong> Testing</a></li><li><ol class="section"><li><a href="ch11-01-writing-tests.html"><strong aria-hidden="true">11.1.</strong> Writing tests</a></li><li><a href="ch11-02-running-tests.html"><strong aria-hidden="true">11.2.</strong> Running tests</a></li><li><a href="ch11-03-test-organization.html"><strong aria-hidden="true">11.3.</strong> Test Organization</a></li></ol></li><li><a href="ch12-00-an-io-project.html"><strong aria-hidden="true">12.</strong> An I/O Project: Building a Command Line Program</a></li><li><ol class="section"><li><a href="ch12-01-accepting-command-line-arguments.html"><strong aria-hidden="true">12.1.</strong> Accepting Command Line Arguments</a></li><li><a href="ch12-02-reading-a-file.html"><strong aria-hidden="true">12.2.</strong> Reading a File</a></li><li><a href="ch12-03-improving-error-handling-and-modularity.html"><strong aria-hidden="true">12.3.</strong> Refactoring to Improve Modularity and Error Handling</a></li><li><a href="ch12-04-testing-the-librarys-functionality.html"><strong aria-hidden="true">12.4.</strong> Developing the Library’s Functionality with Test Driven Development</a></li><li><a href="ch12-05-working-with-environment-variables.html"><strong aria-hidden="true">12.5.</strong> Working with Environment Variables</a></li><li><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong aria-hidden="true">12.6.</strong> Writing Error Messages to Standard Error Instead of Standard Output</a></li></ol></li><li><a href="ch13-00-functional-features.html"><strong aria-hidden="true">13.</strong> Functional Language Features: Iterators and Closures</a></li><li><ol class="section"><li><a href="ch13-01-closures.html"><strong aria-hidden="true">13.1.</strong> Closures: Anonymous Functions that Can Capture Their Environment</a></li><li><a href="ch13-02-iterators.html"><strong aria-hidden="true">13.2.</strong> Processing a Series of Items with Iterators</a></li><li><a href="ch13-03-improving-our-io-project.html"><strong aria-hidden="true">13.3.</strong> Improving Our I/O Project</a></li><li><a href="ch13-04-performance.html"><strong aria-hidden="true">13.4.</strong> Comparing Performance: Loops vs. Iterators</a></li></ol></li><li><a href="ch14-00-more-about-cargo.html"><strong aria-hidden="true">14.</strong> More about Cargo and Crates.io</a></li><li><ol class="section"><li><a href="ch14-01-release-profiles.html"><strong aria-hidden="true">14.1.</strong> Customizing Builds with Release Profiles</a></li><li><a href="ch14-02-publishing-to-crates-io.html"><strong aria-hidden="true">14.2.</strong> Publishing a Crate to Crates.io</a></li><li><a href="ch14-03-cargo-workspaces.html"><strong aria-hidden="true">14.3.</strong> Cargo Workspaces</a></li><li><a href="ch14-04-installing-binaries.html"><strong aria-hidden="true">14.4.</strong> Installing Binaries from Crates.io with cargo install</a></li><li><a href="ch14-05-extending-cargo.html"><strong aria-hidden="true">14.5.</strong> Extending Cargo with Custom Commands</a></li></ol></li><li><a href="ch15-00-smart-pointers.html"><strong aria-hidden="true">15.</strong> Smart Pointers</a></li><li><ol class="section"><li><a href="ch15-01-box.html"><strong aria-hidden="true">15.1.</strong> Box<T> Points to Data on the Heap and Has a Known Size</a></li><li><a href="ch15-02-deref.html"><strong aria-hidden="true">15.2.</strong> The Deref Trait Allows Access to the Data Through a Reference</a></li><li><a href="ch15-03-drop.html"><strong aria-hidden="true">15.3.</strong> The Drop Trait Runs Code on Cleanup</a></li><li><a href="ch15-04-rc.html"><strong aria-hidden="true">15.4.</strong> Rc<T>, the Reference Counted Smart Pointer</a></li><li><a href="ch15-05-interior-mutability.html" class="active"><strong aria-hidden="true">15.5.</strong> RefCell<T> and the Interior Mutability Pattern</a></li><li><a href="ch15-06-reference-cycles.html"><strong aria-hidden="true">15.6.</strong> Creating Reference Cycles and Leaking Memory is Safe</a></li></ol></li><li><a href="ch16-00-concurrency.html"><strong aria-hidden="true">16.</strong> Fearless Concurrency</a></li><li><ol class="section"><li><a href="ch16-01-threads.html"><strong aria-hidden="true">16.1.</strong> Threads</a></li><li><a href="ch16-02-message-passing.html"><strong aria-hidden="true">16.2.</strong> Message Passing</a></li><li><a href="ch16-03-shared-state.html"><strong aria-hidden="true">16.3.</strong> Shared State</a></li><li><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong aria-hidden="true">16.4.</strong> Extensible Concurrency: Sync and Send</a></li></ol></li><li><a href="ch17-00-oop.html"><strong aria-hidden="true">17.</strong> Object Oriented Programming Features of Rust</a></li><li><ol class="section"><li><a href="ch17-01-what-is-oo.html"><strong aria-hidden="true">17.1.</strong> Characteristics of Object-Oriented Languages</a></li><li><a href="ch17-02-trait-objects.html"><strong aria-hidden="true">17.2.</strong> Using Trait Objects that Allow for Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong aria-hidden="true">17.3.</strong> Implementing an Object-Oriented Design Pattern</a></li></ol></li><li><a href="ch18-00-patterns.html"><strong aria-hidden="true">18.</strong> Patterns Match the Structure of Values</a></li><li><ol class="section"><li><a href="ch18-01-all-the-places-for-patterns.html"><strong aria-hidden="true">18.1.</strong> All the Places Patterns May be Used</a></li><li><a href="ch18-02-refutability.html"><strong aria-hidden="true">18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li><a href="ch18-03-pattern-syntax.html"><strong aria-hidden="true">18.3.</strong> All the Pattern Syntax</a></li></ol></li><li><a href="ch19-00-advanced-features.html"><strong aria-hidden="true">19.</strong> Advanced Features</a></li><li><ol class="section"><li><a href="ch19-01-unsafe-rust.html"><strong aria-hidden="true">19.1.</strong> Unsafe Rust</a></li><li><a href="ch19-02-advanced-lifetimes.html"><strong aria-hidden="true">19.2.</strong> Advanced Lifetimes</a></li><li><a href="ch19-03-advanced-traits.html"><strong aria-hidden="true">19.3.</strong> Advanced Traits</a></li><li><a href="ch19-04-advanced-types.html"><strong aria-hidden="true">19.4.</strong> Advanced Types</a></li><li><a href="ch19-05-advanced-functions-and-closures.html"><strong aria-hidden="true">19.5.</strong> Advanced Functions & Closures</a></li></ol></li><li><a href="ch20-00-final-project-a-web-server.html"><strong aria-hidden="true">20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ol class="section"><li><a href="ch20-01-single-threaded.html"><strong aria-hidden="true">20.1.</strong> A Single Threaded Web Server</a></li><li><a href="ch20-02-multithreaded.html"><strong aria-hidden="true">20.2.</strong> Turning our Single Threaded Server into a Multithreaded Server</a></li><li><a href="ch20-03-graceful-shutdown-and-cleanup.html"><strong aria-hidden="true">20.3.</strong> Graceful Shutdown and Cleanup</a></li></ol></li><li><a href="appendix-00.html"><strong aria-hidden="true">21.</strong> Appendix</a></li><li><ol class="section"><li><a href="appendix-01-keywords.html"><strong aria-hidden="true">21.1.</strong> A - Keywords</a></li><li><a href="appendix-02-operators.html"><strong aria-hidden="true">21.2.</strong> B - Operators and Symbols</a></li><li><a href="appendix-03-derivable-traits.html"><strong aria-hidden="true">21.3.</strong> C - Derivable Traits</a></li><li><a href="appendix-04-macros.html"><strong aria-hidden="true">21.4.</strong> D - Macros</a></li><li><a href="appendix-05-translation.html"><strong aria-hidden="true">21.5.</strong> E - Translations</a></li><li><a href="appendix-06-nightly-rust.html"><strong aria-hidden="true">21.6.</strong> F - How Rust is Made and “Nightly Rust”</a></li></ol></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="ch15-05-interior-mutability.html#refcellt-and-the-interior-mutability-pattern" id="refcellt-and-the-interior-mutability-pattern"><h2><code>RefCell<T></code> and the Interior Mutability Pattern</h2></a>
<!-- NEXT PARAGRAPH WRAPPED WEIRD INTENTIONALLY SEE #199 -->
<p><em>Interior mutability</em> is a design pattern in Rust that allows you to mutate
data even when there are immutable references to that data; normally, this
action is disallowed by the borrowing rules. To mutate data, the pattern uses
<code>unsafe</code> code inside a data structure to bend Rust’s usual rules that govern
mutation and borrowing. We haven’t yet covered unsafe code; we will in
Chapter 19. We can use types that use the interior mutability pattern when we
can ensure that the borrowing rules will be followed at runtime, even though
the compiler can’t guarantee that. The <code>unsafe</code> code involved is then wrapped
in a safe API, and the outer type is still immutable.</p>
<p>Let’s explore this concept by looking at the <code>RefCell<T></code> type that follows the
interior mutability pattern.</p>
<a class="header" href="ch15-05-interior-mutability.html#enforcing-borrowing-rules-at-runtime-with-refcellt" id="enforcing-borrowing-rules-at-runtime-with-refcellt"><h3>Enforcing Borrowing Rules at Runtime with <code>RefCell<T></code></h3></a>
<p>Unlike <code>Rc<T></code>, the <code>RefCell<T></code> type represents single ownership over the data
it holds. So, what makes <code>RefCell<T></code> different from a type like <code>Box<T></code>?
Recall the borrowing rules you learned in Chapter 4:</p>
<ul>
<li>At any given time, you can have <em>either</em> (but not both of) one mutable
reference or any number of immutable references.</li>
<li>References must always be valid.</li>
</ul>
<p>With references and <code>Box<T></code>, the borrowing rules’ invariants are enforced at
compile time. With <code>RefCell<T></code>, these invariants are enforced <em>at runtime</em>.
With references, if you break these rules, you’ll get a compiler error. With
<code>RefCell<T></code>, if you break these rules, your program will panic and exit.</p>
<p>The advantages of checking the borrowing rules at compile time are that errors
will be caught sooner in the development process, and there is no impact on
runtime performance because all the analysis is completed beforehand. For those
reasons, checking the borrowing rules at compile time is the best choice in the
majority of cases, which is why this is Rust’s default.</p>
<p>The advantage of checking the borrowing rules at runtime instead is that
certain memory-safe scenarios are then allowed, whereas they are disallowed by
the compile-time checks. Static analysis, like the Rust compiler, is inherently
conservative. Some properties of code are impossible to detect by analyzing the
code: the most famous example is the Halting Problem, which is beyond the scope
of this book but is an interesting topic to research.</p>
<p>Because some analysis is impossible, if the Rust compiler can’t be sure the
code complies with the ownership rules, it might reject a correct program; in
this way, it’s conservative. If Rust accepted an incorrect program, users
wouldn’t be able to trust in the guarantees Rust makes. However, if Rust
rejects a correct program, the programmer will be inconvenienced, but nothing
catastrophic can occur. The <code>RefCell<T></code> type is useful when you’re sure your
code follows the borrowing rules but the compiler is unable to understand and
guarantee that.</p>
<p>Similar to <code>Rc<T></code>, <code>RefCell<T></code> is only for use in single-threaded scenarios
and will give you a compile-time error if you try using it in a multithreaded
context. We’ll talk about how to get the functionality of <code>RefCell<T></code> in a
multithreaded program in Chapter 16.</p>
<p>Here is a recap of the reasons to choose <code>Box<T></code>, <code>Rc<T></code>, or <code>RefCell<T></code>:</p>
<ul>
<li><code>Rc<T></code> enables multiple owners of the same data; <code>Box<T></code> and <code>RefCell<T></code>
have single owners.</li>
<li><code>Box<T></code> allows immutable or mutable borrows checked at compile time; <code>Rc<T></code>
allows only immutable borrows checked at compile time; <code>RefCell<T></code> allows
immutable or mutable borrows checked at runtime.</li>
<li>Because <code>RefCell<T></code> allows mutable borrows checked at runtime, you can
mutate the value inside the <code>RefCell<T></code> even when the <code>RefCell<T></code> is
immutable.</li>
</ul>
<p>Mutating the value inside an immutable value is the <em>interior mutability</em>
pattern. Let’s look at a situation in which interior mutability is useful and
examine how it’s possible.</p>
<a class="header" href="ch15-05-interior-mutability.html#interior-mutability-a-mutable-borrow-to-an-immutable-value" id="interior-mutability-a-mutable-borrow-to-an-immutable-value"><h3>Interior Mutability: A Mutable Borrow to an Immutable Value</h3></a>
<p>A consequence of the borrowing rules is that when you have an immutable value,
you can’t borrow it mutably. For example, this code won’t compile:</p>
<pre><code class="language-rust ignore">fn main() {
let x = 5;
let y = &mut x;
}
</code></pre>
<p>If you tried to compile this code, you’d get the following error:</p>
<pre><code class="language-text">error[E0596]: cannot borrow immutable local variable `x` as mutable
--> src/main.rs:3:18
|
2 | let x = 5;
| - consider changing this to `mut x`
3 | let y = &mut x;
| ^ cannot borrow mutably
</code></pre>
<p>However, there are situations in which it would be useful for a value to mutate
itself in its methods but appear immutable to other code. Code outside the
value’s methods would not be able to mutate the value. Using <code>RefCell<T></code> is
one way to get the ability to have interior mutability. But <code>RefCell<T></code>
doesn’t get around the borrowing rules completely: the borrow checker in the
compiler allows this interior mutability, and the borrowing rules are checked
at runtime instead. If you violate the rules, you’ll get a <code>panic!</code> instead of
a compiler error.</p>
<p>Let’s work through a practical example where we can use <code>RefCell<T></code> to mutate
an immutable value and see why that is useful.</p>
<a class="header" href="ch15-05-interior-mutability.html#a-use-case-for-interior-mutability-mock-objects" id="a-use-case-for-interior-mutability-mock-objects"><h4>A Use Case for Interior Mutability: Mock Objects</h4></a>
<p>A <em>test double</em> is the general programming concept for a type used in place of
another type during testing. <em>Mock objects</em> are specific types of test doubles
that record what happens during a test so you can assert that the correct
actions took place.</p>
<p>Rust doesn’t have objects in the same sense as other languages have objects,
and Rust doesn’t have mock object functionality built into the standard library
as some other languages do. However, you can definitely create a struct that
will serve the same purposes as a mock object.</p>
<p>Here’s the scenario we’ll test: we’ll create a library that tracks a value
against a maximum value and sends messages based on how close to the maximum
value the current value is. This library could be used to keep track of a
user’s quota for the number of API calls they’re allowed to make, for example.</p>
<p>Our library will only provide the functionality of tracking how close to the
maximum a value is and what the messages should be at what times. Applications
that use our library will be expected to provide the mechanism for sending the
messages: the application could put a message in the application, send an
email, send a text message, or something else. The library doesn’t need to know
that detail. All it needs is something that implements a trait we’ll provide
called <code>Messenger</code>. Listing 15-20 shows the library code:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
pub trait Messenger {
fn send(&self, msg: &str);
}
pub struct LimitTracker<'a, T: 'a + Messenger> {
messenger: &'a T,
value: usize,
max: usize,
}
impl<'a, T> LimitTracker<'a, T>
where T: Messenger {
pub fn new(messenger: &T, max: usize) -> LimitTracker<T> {
LimitTracker {
messenger,
value: 0,
max,
}
}
pub fn set_value(&mut self, value: usize) {
self.value = value;
let percentage_of_max = self.value as f64 / self.max as f64;
if percentage_of_max >= 0.75 && percentage_of_max < 0.9 {
self.messenger.send("Warning: You've used up over 75% of your quota!");
} else if percentage_of_max >= 0.9 && percentage_of_max < 1.0 {
self.messenger.send("Urgent warning: You've used up over 90% of your quota!");
} else if percentage_of_max >= 1.0 {
self.messenger.send("Error: You are over your quota!");
}
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 15-20: A library to keep track of how close a
value is to a maximum value and warn when the value is at certain levels</span></p>
<p>One important part of this code is that the <code>Messenger</code> trait has one method
called <code>send</code> that takes an immutable reference to <code>self</code> and the text of the
message. This is the interface our mock object needs to have. The other
important part is that we want to test the behavior of the <code>set_value</code> method
on the <code>LimitTracker</code>. We can change what we pass in for the <code>value</code> parameter,
but <code>set_value</code> doesn’t return anything for us to make assertions on. We want
to be able to say that if we create a <code>LimitTracker</code> with something that
implements the <code>Messenger</code> trait and a particular value for <code>max</code>, when we pass
different numbers for <code>value</code>, the messenger is told to send the appropriate
messages.</p>
<p>We need a mock object that, instead of sending an email or text message when we
call <code>send</code>, will only keep track of the messages it’s told to send. We can
create a new instance of the mock object, create a <code>LimitTracker</code> that uses the
mock object, call the <code>set_value</code> method on <code>LimitTracker</code>, and then check that
the mock object has the messages we expect. Listing 15-21 shows an attempt to
implement a mock object to do just that, but the borrow checker won’t allow it:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[cfg(test)]
mod tests {
use super::*;
struct MockMessenger {
sent_messages: Vec<String>,
}
impl MockMessenger {
fn new() -> MockMessenger {
MockMessenger { sent_messages: vec![] }
}
}
impl Messenger for MockMessenger {
fn send(&self, message: &str) {
self.sent_messages.push(String::from(message));
}
}
#[test]
fn it_sends_an_over_75_percent_warning_message() {
let mock_messenger = MockMessenger::new();
let mut limit_tracker = LimitTracker::new(&mock_messenger, 100);
limit_tracker.set_value(80);
assert_eq!(mock_messenger.sent_messages.len(), 1);
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 15-21: An attempt to implement a <code>MockMessenger</code>
that isn’t allowed by the borrow checker</span></p>
<p>This test code defines a <code>MockMessenger</code> struct that has a <code>sent_messages</code>
field with a <code>Vec</code> of <code>String</code> values to keep track of the messages it’s told
to send. We also define an associated function <code>new</code> to make it convenient to
create new <code>MockMessenger</code> values that start with an empty list of messages. We
then implement the <code>Messenger</code> trait for <code>MockMessenger</code> so we can give a
<code>MockMessenger</code> to a <code>LimitTracker</code>. In the definition of the <code>send</code> method, we
take the message passed in as a parameter and store it in the <code>MockMessenger</code>
list of <code>sent_messages</code>.</p>
<p>In the test, we’re testing what happens when the <code>LimitTracker</code> is told to set
<code>value</code> to something that is more than 75 percent of the <code>max</code> value. First, we
create a new <code>MockMessenger</code>, which will start with an empty list of messages.
Then we create a new <code>LimitTracker</code> and give it a reference to the new
<code>MockMessenger</code> and a <code>max</code> value of 100. We call the <code>set_value</code> method on the
<code>LimitTracker</code> with a value of 80, which is more than 75 percent of 100. Then
we assert that the list of messages that the <code>MockMessenger</code> is keeping track
of should now have one message in it.</p>
<p>However, there’s one problem with this test, as shown here:</p>
<pre><code class="language-text">error[E0596]: cannot borrow immutable field `self.sent_messages` as mutable
--> src/lib.rs:52:13
|
51 | fn send(&self, message: &str) {
| ----- use `&mut self` here to make mutable
52 | self.sent_messages.push(String::from(message));
| ^^^^^^^^^^^^^^^^^^ cannot mutably borrow immutable field
</code></pre>
<p>We can’t modify the <code>MockMessenger</code> to keep track of the messages, because the
<code>send</code> method takes an immutable reference to <code>self</code>. We also can’t take the
suggestion from the error text to use <code>&mut self</code> instead, because then the
signature of <code>send</code> wouldn’t match the signature in the <code>Messenger</code> trait
definition (feel free to try and see what error message you get).</p>
<p>This is a situation in which interior mutability can help! We’ll store the
<code>sent_messages</code> within a <code>RefCell<T></code>, and then the <code>send</code> message will be
able to modify <code>sent_messages</code> to store the messages we’ve seen. Listing 15-22
shows what that looks like:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[cfg(test)]
mod tests {
use super::*;
use std::cell::RefCell;
struct MockMessenger {
sent_messages: RefCell<Vec<String>>,
}
impl MockMessenger {
fn new() -> MockMessenger {
MockMessenger { sent_messages: RefCell::new(vec![]) }
}
}
impl Messenger for MockMessenger {
fn send(&self, message: &str) {
self.sent_messages.borrow_mut().push(String::from(message));
}
}
#[test]
fn it_sends_an_over_75_percent_warning_message() {
// --snip--
# let mock_messenger = MockMessenger::new();
# let mut limit_tracker = LimitTracker::new(&mock_messenger, 100);
# limit_tracker.set_value(75);
assert_eq!(mock_messenger.sent_messages.borrow().len(), 1);
}
}
#}</code></pre></pre>
<p><span class="caption">Listing 15-22: Using <code>RefCell<T></code> to mutate an inner
value while the outer value is considered immutable</span></p>
<p>The <code>sent_messages</code> field is now of type <code>RefCell<Vec<String>></code> instead of
<code>Vec<String></code>. In the <code>new</code> function, we create a new <code>RefCell<Vec<String>></code>
instance around the empty vector.</p>
<p>For the implementation of the <code>send</code> method, the first parameter is still an
immutable borrow of <code>self</code>, which matches the trait definition. We call
<code>borrow_mut</code> on the <code>RefCell<Vec<String>></code> in <code>self.sent_messages</code> to get a
mutable reference to the value inside the <code>RefCell<Vec<String>></code>, which is
the vector. Then we can call <code>push</code> on the mutable reference to the vector to
keep track of the messages sent during the test.</p>
<p>The last change we have to make is in the assertion: to see how many items are
in the inner vector, we call <code>borrow</code> on the <code>RefCell<Vec<String>></code> to get an
immutable reference to the vector.</p>
<p>Now that you’ve seen how to use <code>RefCell<T></code>, let’s dig into how it works!</p>
<a class="header" href="ch15-05-interior-mutability.html#keeping-track-of-borrows-at-runtime-with-refcellt" id="keeping-track-of-borrows-at-runtime-with-refcellt"><h4>Keeping Track of Borrows at Runtime with <code>RefCell<T></code></h4></a>
<p>When creating immutable and mutable references, we use the <code>&</code> and <code>&mut</code>
syntax, respectively. With <code>RefCell<T></code>, we use the <code>borrow</code> and <code>borrow_mut</code>
methods, which are part of the safe API that belongs to <code>RefCell<T></code>. The
<code>borrow</code> method returns the smart pointer type <code>Ref<T></code>, and <code>borrow_mut</code>
returns the smart pointer type <code>RefMut<T></code>. Both types implement <code>Deref</code>, so we
can treat them like regular references.</p>
<p>The <code>RefCell<T></code> keeps track of how many <code>Ref<T></code> and <code>RefMut<T></code> smart
pointers are currently active. Every time we call <code>borrow</code>, the <code>RefCell<T></code>
increases its count of how many immutable borrows are active. When a <code>Ref<T></code>
value goes out of scope, the count of immutable borrows goes down by one. Just
like the compile-time borrowing rules, <code>RefCell<T></code> lets us have many immutable
borrows or one mutable borrow at any point in time.</p>
<p>If we try to violate these rules, rather than getting a compiler error as we
would with references, the implementation of <code>RefCell<T></code> will panic at
runtime. Listing 15-23 shows a modification of the implementation of <code>send</code> in
Listing 15-22. We’re deliberately trying to create two mutable borrows active
for the same scope to illustrate that <code>RefCell<T></code> prevents us from doing this
at runtime.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><code class="language-rust ignore">impl Messenger for MockMessenger {
fn send(&self, message: &str) {
let mut one_borrow = self.sent_messages.borrow_mut();
let mut two_borrow = self.sent_messages.borrow_mut();
one_borrow.push(String::from(message));
two_borrow.push(String::from(message));
}
}
</code></pre>
<p><span class="caption">Listing 15-23: Creating two mutable references in the
same scope to see that <code>RefCell<T></code> will panic</span></p>
<p>We create a variable <code>one_borrow</code> for the <code>RefMut<T></code> smart pointer returned
from <code>borrow_mut</code>. Then we create another mutable borrow in the same way in the
variable <code>two_borrow</code>. This makes two mutable references in the same scope,
which isn’t allowed. When we run the tests for our library, the code in Listing
15-23 will compile without any errors, but the test will fail:</p>
<pre><code class="language-text">---- tests::it_sends_an_over_75_percent_warning_message stdout ----
thread 'tests::it_sends_an_over_75_percent_warning_message' panicked at
'already borrowed: BorrowMutError', src/libcore/result.rs:906:4
note: Run with `RUST_BACKTRACE=1` for a backtrace.
</code></pre>
<p>Notice that the code panicked with the message <code>already borrowed: BorrowMutError</code>. This is how <code>RefCell<T></code> handles violations of the borrowing
rules at runtime.</p>
<p>Catching borrowing errors at runtime rather than compile time means that you
would find a mistake in your code later in the development process and possibly
not until your code was deployed to production. Also, your code would incur a
small runtime performance penalty as a result of keeping track of the borrows
at runtime rather than compile time. However, using <code>RefCell<T></code> makes it
possible to write a mock object that can modify itself to keep track of the
messages it has seen while you’re using it in a context where only immutable
values are allowed. You can use <code>RefCell<T></code> despite its trade-offs to get more
functionality than regular references provide.</p>
<a class="header" href="ch15-05-interior-mutability.html#having-multiple-owners-of-mutable-data-by-combining-rct-and-refcellt" id="having-multiple-owners-of-mutable-data-by-combining-rct-and-refcellt"><h3>Having Multiple Owners of Mutable Data by Combining <code>Rc<T></code> and <code>RefCell<T></code></h3></a>
<p>A common way to use <code>RefCell<T></code> is in combination with <code>Rc<T></code>. Recall that
<code>Rc<T></code> lets you have multiple owners of some data, but it only gives immutable
access to that data. If you have an <code>Rc<T></code> that holds a <code>RefCell<T></code>, you can
get a value that can have multiple owners <em>and</em> that you can mutate!</p>
<p>For example, recall the cons list example in Listing 15-18 where we used
<code>Rc<T></code> to allow multiple lists to share ownership of another list. Because
<code>Rc<T></code> holds only immutable values, we can’t change any of the values in the
list once we’ve created them. Let’s add in <code>RefCell<T></code> to gain the ability to
change the values in the lists. Listing 15-24 shows that by using a
<code>RefCell<T></code> in the <code>Cons</code> definition, we can modify the value stored in all
the lists:</p>
<p><span class="filename">Filename: src/main.rs</span></p>
<pre><pre class="playpen"><code class="language-rust">#[derive(Debug)]
enum List {
Cons(Rc<RefCell<i32>>, Rc<List>),
Nil,
}
use List::{Cons, Nil};
use std::rc::Rc;
use std::cell::RefCell;
fn main() {
let value = Rc::new(RefCell::new(5));
let a = Rc::new(Cons(Rc::clone(&value), Rc::new(Nil)));
let b = Cons(Rc::new(RefCell::new(6)), Rc::clone(&a));
let c = Cons(Rc::new(RefCell::new(10)), Rc::clone(&a));
*value.borrow_mut() += 10;
println!("a after = {:?}", a);
println!("b after = {:?}", b);
println!("c after = {:?}", c);
}
</code></pre></pre>
<p><span class="caption">Listing 15-24: Using <code>Rc<RefCell<i32>></code> to create a
<code>List</code> that we can mutate</span></p>
<p>We create a value that is an instance of <code>Rc<RefCell<i32>></code> and store it in a
variable named <code>value</code> so we can access it directly later. Then we create a
<code>List</code> in <code>a</code> with a <code>Cons</code> variant that holds <code>value</code>. We need to clone
<code>value</code> so both <code>a</code> and <code>value</code> have ownership of the inner <code>5</code> value rather
than transferring ownership from <code>value</code> to <code>a</code> or having <code>a</code> borrow from
<code>value</code>.</p>
<p>We wrap the list <code>a</code> in an <code>Rc<T></code> so when we create lists <code>b</code> and <code>c</code>, they
can both refer to <code>a</code>, which is what we did in Listing 15-18.</p>
<p>After we’ve created the lists in <code>a</code>, <code>b</code>, and <code>c</code>, we add 10 to the value in
<code>value</code>. We do this by calling <code>borrow_mut</code> on <code>value</code>, which uses the
automatic dereferencing feature we discussed in Chapter 5 (see the section
“Where’s the <code>-></code> Operator?”) to dereference the <code>Rc<T></code> to the inner
<code>RefCell<T></code> value. The <code>borrow_mut</code> method returns a <code>RefMut<T></code> smart
pointer, and we use the dereference operator on it and change the inner value.</p>
<p>When we print <code>a</code>, <code>b</code>, and <code>c</code>, we can see that they all have the modified
value of 15 rather than 5:</p>
<pre><code class="language-text">a after = Cons(RefCell { value: 15 }, Nil)
b after = Cons(RefCell { value: 6 }, Cons(RefCell { value: 15 }, Nil))
c after = Cons(RefCell { value: 10 }, Cons(RefCell { value: 15 }, Nil))
</code></pre>
<p>This technique is pretty neat! By using <code>RefCell<T></code>, we have an outwardly
immutable <code>List</code> value. But we can use the methods on <code>RefCell<T></code> that provide
access to its interior mutability so we can modify our data when we need to.
The runtime checks of the borrowing rules protect us from data races, and it’s
sometimes worth trading a bit of speed for this flexibility in our data
structures.</p>
<p>The standard library has other types that provide interior mutability, such as
<code>Cell<T></code>, which is similar except that instead of giving references to the
inner value, the value is copied in and out of the <code>Cell<T></code>. There’s also
<code>Mutex<T></code>, which offers interior mutability that’s safe to use across threads;
we’ll discuss its use in Chapter 16. Check out the standard library docs for
more details on the differences between these types.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch15-04-rc.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="ch15-06-reference-cycles.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="ch15-04-rc.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch15-06-reference-cycles.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
548
