The Accelerated Guide to SMART POINTERS IN RUST TIM McNAMARA accelerant.dev First © Tim McNamara 2023 (paperback) (EPUB) (Kindle) (PDF) A catalogue record for this book is available from the National Library of New Zealand. Kei te pātengi raraunga o Te Puna Mātauranga o Aotearoa te whakarārangi o tēnei pukapuka. The Accelerated Guide to Smart Pointers in Rust Tim McNamara A short textbook for anyone who’s interested in understanding about Rust’s smart pointers, including people who don’t know what smart pointers are. Introduction In this guide, we embark on a journey to explore the various types of smart pointers available in Rust, their use cases, and how they contribute to managing memory safely and efficiently. In some sense, they are the essence of Rust’s “zero-cost abstraction” philosophy, whereby you only pay for what you use. Smart pointers are powerful tools that provide additional functionality and guarantees compared to raw pointers. If you’re unsure what a raw pointer is, that’s okay, we’ll discuss that too. We’ll cover the core smart pointer types in Rust, including Box , Rc , Arc , RefCell , and Mutex . Each type will be thoroughly explained, accompanied by practical code examples that are linked directly in the Rust playground, so you can run them in your web browser. Furthermore, we will delve into best practices and common pitfalls associated with using smart pointers in Rust. This knowledge will empower you to write robust, efficient, and maintainable code while avoiding potential pitfalls along the way. Whether you are a Rust enthusiast, a curious learner, or a seasoned developer looking to enhance your memory management skills, this guide is here to support your journey. So let’s dive in and unlock the power of smart pointers in Rust! We begin by learning about what the term “smart pointer” actually means. Contents 2. Defining smart pointers .................................................................................... 6 3. Understanding Rust ............................................................................................ 8 3.1. Ownership ...................................................................................................... 10 3.2. Borrowing ....................................................................................................... 12 3.3. Lifetimes ........................................................................................................ 14 4. Defining smart pointers, again .................................................................... 19 5. Why use them? .................................................................................................... 21 5.1. Automatic memory management ...................................................... 22 5.2. Prevent data races ................................................................................... 23 5.3. Add super powers to pointers ............................................................ 25 5.4. Simplify code .............................................................................................. 26 6. Stdlib’s smart pointers .................................................................................... 27 6.1. Box ........................................................................................................... 28 6.2. Rc ............................................................................................................. 32 6.3. Arc ........................................................................................................... 36 6.4. RefCell ................................................................................................... 39 6.5. Mutex ..................................................................................................... 42 6.6. RwLock .................................................................................................. 45 7. Building your own smart pointers .............................................................. 47 7.1. Drop .................................................................................................................. 48 7.2. Deref ................................................................................................................ 54 7.3. DerefMut ....................................................................................................... 58 8. Extension topics ................................................................................................ 62 8.1. Cyclic data structures ............................................................................. 63 8.2. Rc from scratch ................................................................................. 64 8.3. PhantomData ...................................................................................... 67 9. Recap ...................................................................................................................... 70 10. Cheat Sheet ........................................................................................................ 71 11. Afterword .............................................................................................................. 73 12. About Tim McNamara .................................................................................... 74 Deﬁning smart pointers A smart pointer is a data structure that not only points to an object in memory but also provides additional features, such as dynamically allocating memory as required or reference counting. By encapsulating these responsibilities, smart pointers can help ensure memory safety and reduce the likelihood of programming errors, such as memory leaks or dangling pointers. In the Rust programming language, smart pointers are an essential tool for safe and efficient memory management while adhering to Rust’s ownership rules. Even if you’re unfamiliar with the term, you have already encountered a smart pointer. The String and its cousin Vec are both smart pointers. As well as holding references to the backing array that’s storing the data, they both provide contain the current length and capacity of that array. Now let’s connect the abstract concept of a smart pointer to some Rust-specific concepts. First, a smart pointer owns the data that it refers to. Some raw pointers, such as Rc offer shared ownership, but that shouldn’t be conflated with the reality that the initial pointer needs to have ownership over whatever it is counting references about. Secondly, smart pointers typically implement Deref where U is the data type that’s being pointed at. This means – along with Rust’s auto-deref behavior – that it’s possible for application programmers to use a smart pointer type in place of its referent largely without fuss. You may have also heard the term fat pointer being used as a synonym for smart pointer, but for the purposes of this document we’ll consider these two terms to be distinct. They’re often used interchangeably because a fat pointer includes some metadata about the referent along side the memory address. That metadata is typically the length. This provides some extra capabilities over a raw pointer – specifically it’s possible to deduce what a valid memory access would be without needing to interpret any bytes. [Sidenote: This contrasts with text strings in C, which require the application to check whether the next byte is NULL ( 0x0 ) whenever it accesses the data.] However, because &T and &mut T are not considered smart pointers in the Rust ecosystem, and because they contain a length field when referring to dynamically-sized types (DSTs), we’ll avoid the use of the term fat pointer. Understanding Rust Rust is a modern, programming language designed with performance, reliability, and productivity in mind. It originated in the world of systems programming and provides low-level control over system resources, similar to languages like C and C++, while offering strong guarantees for memory safety and thread safety, like managed languages such as Java and Python. Its expressive type system is much closer to something like Haskell than C. Its no-fuss build system has enabled a rich ecosystem of 3rd party packages. Memory safety is a crucial aspect of Rust. The language eliminates common programming errors at compile time, such as null pointer dereferences, buffer overflows, and many—but not all—data races, which can lead to security vulnerabilities and hard-to-debug issues. Rust achieves this by introducing a unique ownership system, coupled with borrowing and lifetime rules, which are checked at compile-time, ensuring that your code is safe without incurring runtime overhead. Smart pointers are a key tool in Rust’s memory management toolkit. They are data structures that not only hold a reference to an object in memory but also provide additional features, such as automatic memory management or reference counting. By using smart pointers, developers can productively work within Rust’s strict ownership and borrowing rules. They are considered a zero cost abstraction because they are a compile-time construct that the compiler “boils away” during the build process. As we begin our journey, it’s essential first to grasp the concepts of ownership, borrowing and lifetimes. If you’ve skipped these concepts so far, please do take the time to read through the next few sections because gaining an understanding of what is happening will be very beneficial to you want to undesrstand how some of the smart pointer types behave.