Forem: Maksim Gritchin

Memory Allocations in Rust

Maksim Gritchin — Tue, 25 Jun 2024 21:24:39 +0000

Introduction

Welcome to this in-depth tutorial on memory allocations in Rust. As a developer, understanding how Rust manages memory is crucial for writing efficient and safe programs. This guide is the result of analysing several expert sources to provide you with a comprehensive overview of memory management, not just in Rust, but in programming languages in general.

It's important to note that some concepts discussed here can be quite complex and may require further research on your part to fully grasp. Don't be discouraged if you find certain topics challenging – memory management is a deep subject, and even experienced developers continually learn new aspects of it.

We'll start with basic concepts that apply to many programming languages and then focus on Rust-specific implementations. By the end of this tutorial, you'll have a solid foundation in Rust's memory allocation strategies and how to implement them effectively in your projects.

Memory Layout Basics

Before we delve into Rust-specific concepts, it's essential to understand the basic memory layout of a program.

Executable Binary Structure

When you compile a Rust program, the result is an executable binary. The operating system kernel provides a continuous range of virtual memory addresses mapped to physical memory addresses for your program to use.

ELF Executable Structure

When discussing the structure of executables, it's crucial to distinguish between the file format on disk and the memory layout during runtime. Let's focus on the Executable and Linkable Format (ELF), commonly used in Linux systems.

ELF File Structure

An ELF file consists of several parts:

ELF Header:
- Contains metadata about the file type, target architecture, entry point, etc.
Program Header Table:
- Describes how to create a process/memory image for runtime execution.
- Defines segments for the loader.
Section Header Table:
- Describes the sections of the file in detail.
- More relevant for linking and debugging.
Sections:
- Contain the actual data and code. Common sections include:
  - .text: Executable code
  - .data: Initialized data
  - .rodata: Read-only data
  - .bss: Uninitialized data (doesn't actually take space in the file)

Key Points

Sections vs Segments:
- Sections are used by the linker and for debugging.
- Segments are used by the loader to create the process image.
Read-Only Nature:
- The executable file itself is typically read-only.
- Writable sections are loaded into writable memory at runtime.
Runtime vs File Structure:
- The file structure (sections) differs from the runtime memory layout.
- The loader uses the program header to set up the runtime memory.

Runtime Memory Layout

When the program is loaded:

The loader reads the program header.
It sets up the process memory according to the defined segments.
This includes setting up the stack and initialising the heap.

It's important to note that stack and heap are runtime concepts and are not present in the executable file itself. They are allocated and managed by the operating system when the program runs. More read Binary Executable

Stack vs Heap

Now, let's focus on the two primary types of memory allocation in Rust: stack and heap.

Stack

The stack is a region of memory that follows a Last-In-First-Out (LIFO) order. It's used for:

Local variables
Function parameters
Return addresses

Key characteristics of stack allocation:

Fast allocation and deallocation
Limited in size (typically 8MB on 64-bit Linux systems for the main thread, 2MB for other threads)
Non-fragmented

Heap

The heap is a region of memory used for dynamic allocation. It's managed by Rust's global allocator trait, which often uses the C library's malloc under the hood. Key characteristics include:

Flexible size
Slower allocation and deallocation compared to the stack
Can lead to fragmentation
Shared among all threads

Function Stack Frames

When a function is called, a new stack frame is created. This frame stores:

Function parameters
Local variables
Return address

The stack pointer keeps track of the top of the stack, changing as functions are called and return.

Rust's Approach to Memory Management

Rust's memory management is built on two key concepts: ownership and borrowing. These rules allow Rust to manage memory without a garbage collector, ensuring memory safety and preventing common issues like null or dangling pointers.

Ownership Rules

General Ownership Rules

Single Owner Principle:
- At any given time, a value in memory is typically owned by a single binding.
- When an owner goes out of scope, Rust automatically deallocates the value.
Move Semantics:
- Assigning a value to another variable typically moves ownership.
- After a move, the original binding can no longer be used.
Borrowing:
- Values can be borrowed without transferring ownership.
- Multiple immutable borrows or one mutable borrow are allowed at a time.

Let's look at an example:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;  // ownership of the string moves to s2

    // println!("{}", s1);  // This would cause a compile-time error
    println!("{}", s2);  // This is fine
}

In this example, s1 initially owns the String. When we assign s1 to s2, the ownership is moved, and s1 is no longer valid.

Exceptions and Special Cases

Constants: const N: u32 = 5; Constants do not have an owner in the traditional sense. They are compile-time constructs, inlined where used.
Statics: static N: u32 = 5; Static items have a fixed memory address for the entire program runtime. They are not owned by any particular part of the code.
References to Compile-Time Constants: let r = &42; These do not follow standard ownership rules.
Temporary Values: println!("{}", String::from("hello")); Created and destroyed within the expression. Not bound to any variable or subject to normal ownership rules.
Primitive Types: Types that implement the Copy trait (like integers, booleans) are copied rather than moved.

Borrowing

Borrowing allows you to refer to a value without taking ownership. There are two types of borrows:

Read-only borrows: Multiple read-only borrows are allowed simultaneously.
Mutable borrows: Only one mutable borrow is allowed at a time.

Here's an example:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s;  // read-only borrow
    let r2 = &s;  // another read-only borrow
    println!("{} and {}", r1, r2);

    let r3 = &mut s;  // mutable borrow
    r3.push_str(", world");
    println!("{}", r3);
}

This borrowing system allows Rust to prevent data races at compile-time, a significant advantage over many other programming languages.

Data Types and Memory Allocation

Understanding how different data types are allocated in memory is crucial for writing efficient Rust code.

Primitive Data Types

Categories of Primitive Types

Scalar Types:
- Integers: i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize
- Floating-point: f32, f64
- Boolean: bool
- Character: char
Compound Types:
- Arrays: [T; N] where T is any type and N is a compile-time constant
- Slices: &[T] and &mut [T]
- Tuples: (T, U, ...) where T, U, etc. can be any types
- String slices: &str
Pointer Types:
- References: &T and &mut T
- Raw pointers: *const T and *mut T
- Function pointers: fn()

The `Copy` Trait

Primitive types above implement the Copy trait.
Arrays [T; N] implement Copy if T implements Copy.
Slices &[T], references &T, and string slices &str always implement Copy, regardless of T.

Storage Location

Primitive types can be stored on either the stack or the heap.
Non-primitive types can also be stored on either the stack or the heap.

// Primitive type on the heap
let boxed_int: Box<i32> = Box::new(5);

// Array (primitive) on the heap
let boxed_array: Box<[i32; 3]> = Box::new([1, 2, 3]);

// Non-primitive type on the stack
struct Point { x: i32, y: i32 }
let point = Point { x: 0, y: 0 };  // Stored on the stack

Memory Layout

Primitive types typically have a fixed, known size at compile-time. This allows for efficient stack allocation and direct manipulation. However, this doesn't mean they're always stack-allocated. The context of use determines the actual storage location. Some scenarios where a typically stack-allocated value might end up on the heap include:

When it's part of a larger data structure that's heap-allocated. For example, if a primitive type is stored in a Vec or Box, it will be on the heap along with the rest of the data structure.
When it's used in a closure that outlives the current stack frame.
When it's returned from a function as part of a heap-allocated structure.

Compound Data Types

Array

Arrays in Rust have a fixed size known at compile time and are stored on the stack. This is different from some popular languages like Python or JavaScript, where arrays (or lists) are dynamically sized and heap-allocated. In Rust:

let arr: [i32; 5] = [1, 2, 3, 4, 5];

This array is entirely stack-allocated, which can lead to very efficient memory use and access patterns for fixed-size collections.

Tuples

Tuples store values of different types and are allocated on the stack. They're laid out in memory contiguously, with potential padding for alignment. For example:

let tup: (i32, f64, u8) = (500, 6.4, 1);

In memory, this tuple might look like:

[4 bytes for i32][4 bytes padding][8 bytes for f64][1 byte for u8][7 bytes padding]

The padding ensures that each element is properly aligned in memory.

Structs

Structs can be named or tuple-like. They are typically allocated on the stack, but their contents can be on the heap if they contain types like String or Vec. Their memory layout is similar to tuples, including potential padding. For example:

struct Point {
    x: i32,
    y: i32,
}

let p = Point { x: 0, y: 0 };

Enums

Enums are stored as a discriminant (usually an integer) to indicate which variant it is, plus enough space to store the largest variant. This allows Rust to optimise memory usage while providing type safety. The memory allocation can be more complex than it first appears:

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

In this enum:

Quit doesn't need any extra space beyond the discriminant.
Move needs space for two i32 values.
Write needs space for a String, which is a pointer to heap memory.
ChangeColor needs space for three i32 values.

The enum will allocate enough space for the largest variant (likely ChangeColor in this case), plus the discriminant. This means even the Quit variant will use the same amount of memory as ChangeColor, but this approach allows for very fast matching and prevents the need for heap allocations for the enum itself.

Dynamic Data Types

Vector

Vectors are resizable and store their data on the heap. They keep track of capacity and length:

let mut vec: Vec<i32> = Vec::new();
vec.push(1);
vec.push(2);

Slice

Slices are views into elements of an array or vector. They use a fat pointer for reference, containing both a pointer to the data and the length. A fat pointer is a pointer that carries additional information beyond just the memory address. In the case of a slice, the fat pointer contains:

A pointer to the first element of the slice in memory
The length of the slice

This additional information allows Rust to perform bounds checking and iterate over the slice efficiently without needing to store this information separately or query it at runtime.

let slice: &[i32] = &arr[1..3];

String

Strings in Rust are similar to vectors but are guaranteed to be UTF-8 encoded. This guarantee means:

Each character in the string is represented by a valid UTF-8 byte sequence.
The string can contain any Unicode character, but they're stored efficiently.
String operations (like indexing) work on UTF-8 boundaries, not raw bytes.

This UTF-8 guarantee allows Rust to provide safe and efficient string handling, avoiding issues like invalid byte sequences or incorrect character boundaries that can occur in languages with less strict string encodings.

let s = String::from("hello");

Stack Allocation in Rust

In Rust, stack allocation is not limited to primitive types or small objects. Rust allows for stack allocation of objects of arbitrary complexity and size, subject only to the stack size limit. This is indeed different from many other programming languages and is an important feature of Rust's memory model. More read Stack and Heap

Key Points:

Arbitrary Complexity: In Rust, you can allocate structs, enums, arrays, and other complex types on the stack, not just primitives.
Size Flexibility: As long as the size is known at compile time and doesn't exceed the stack limit, you can allocate large objects on the stack.
Performance Implications: Stack allocation is generally faster than heap allocation, so this feature can lead to performance benefits.
Stack Size Limit: While you can allocate complex objects on the stack, you still need to be aware of the stack size limit, which is typically much smaller than the heap.

Memory Allocators in Rust

Rust provides flexibility in choosing memory allocators. Let's explore some common options:

Standard Allocator

The standard allocator in Rust uses the system's default allocator (often the C library's malloc). It's a good general-purpose allocator but may not be the most efficient for all scenarios.

Characteristics:

Uses sbrk to grow the heap
Memory is counted towards Resident Set Size (RSS)
Not the fastest or most memory-efficient
Low memory footprint upon initialization

jemalloc

jemalloc is a popular alternative allocator known for its efficiency in multi-threaded environments.

Characteristics:

Uses mmap to allocate memory
Memory only counts towards RSS when written to
Efficient in managing "dirty" pages (memory freed but not returned to OS)
High initial memory footprint
Can be tuned for performance or memory efficiency for heavy workloads

To use jemalloc in your Rust project:

Add it to your Cargo.toml:

   [dependencies]
   jemallocator = "0.3.2"

Set it as the global allocator in your main Rust file:

   use jemallocator::Jemalloc;

   #[global_allocator]
   static GLOBAL: Jemalloc = Jemalloc;

Microsoft's mimalloc

mimalloc is another high-performance allocator known for its speed and low initial memory footprint.

Characteristics:

Very fast
Low initial memory footprint
Good choice for applications that require quick startup times

Advanced Memory Management Techniques

Using `Box<T>` for Heap Allocation

When you need to allocate memory on the heap explicitly, Rust provides the Box<T> type. This is useful for recursive data structures or when you need to ensure a value has a stable memory address.

fn main() {
    let b = Box::new(5);
    println!("b = {}", b);
}

When b goes out of scope, the heap memory is automatically deallocated.

Reference Counting with `Rc<T>`

For scenarios where you need shared ownership of data (e.g., in graph-like structures), Rust provides Rc<T> (Reference Counted).

use std::rc::Rc;

fn main() {
    let a = Rc::new(String::from("Hello"));
    let b = a.clone();  // Increases the reference count

    println!("a: {}, b: {}", a, b);
}

Rc<T> keeps track of the number of references to a value and only deallocates the value when the reference count reaches zero.

Atomic Reference Counting with `Arc<T>`

For thread-safe reference counting, Rust provides Arc<T> (Atomic Reference Counted). It's similar to Rc<T> but safe to use across multiple threads.

use std::sync::Arc;
use std::thread;

fn main() {
    let s = Arc::new(String::from("shared data"));

    for _ in 0..10 {
        let s = Arc::clone(&s);
        thread::spawn(move || {
            println!("{}", s);
        });
    }
}

Optimising Memory Usage

Struct Layout

Rust allows you to optimise memory usage by considering struct layout. Let's look at an example and explain the paddings:

struct Efficient {
    a: i32,
    b: i32,
    c: i16,
}

struct Inefficient {
    a: i32,
    c: i16,
    b: i32,
}

In the Efficient struct:

a occupies 4 bytes
b occupies the next 4 bytes
c occupies the next 2 bytes
Total: 10 bytes

In the Inefficient struct:

a occupies 4 bytes
c occupies the next 2 bytes
2 bytes of padding are added to align b
b occupies the next 4 bytes
Total: 12 bytes

The Efficient struct uses less memory due to better alignment and less padding. The compiler adds padding to ensure that each field is aligned to its natural alignment (usually its size). By ordering fields from largest to smallest, we can often reduce the amount of padding needed.

Copy vs Clone

Understanding the difference between Copy and Clone traits can help you optimise memory usage:

Copy: Allows bitwise copying of values. Use for small, stack-allocated types.
Clone: Allows more complex copying logic. Use for heap-allocated or larger types.

#[derive(Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

#[derive(Clone)]
struct ComplexData {
    data: Vec<i32>,
}

Option Type Optimization

Rust's Option type is optimized to avoid null pointers. For types that cannot be null (like Box<T>), Rust uses a clever optimization where the None variant doesn't take up any extra space.

enum Option<T> {
    Some(T),
    None,
}

let x: Option<Box<i32>> = None;

In this case, x doesn't allocate any heap memory.

Advanced Concepts

Memory Pages and Virtual Memory

Understanding how the operating system manages memory can help you write more efficient Rust code. The OS allocates memory in pages (usually 4096 bytes). When your program requests memory, it's given in multiples of these pages.

Virtual Memory allows your program to use more memory than is physically available. The OS maps virtual memory addresses to physical memory or disk storage.

Resident Set Size (RSS) vs Virtual Memory

Virtual Memory: The amount of memory your program can use.
RSS (Resident Set Size): The actual memory used by your program.

Different allocators manage these differently. For example, jemalloc uses mmap to allocate memory, which only counts towards RSS when written to.

Tuning jemalloc

jemalloc offers various tuning options:

Multiple arenas to limit fragmentation
Background cleanup threads
Profiling options to monitor memory usage

These can be configured through environment variables or at runtime.

Best Practices for Memory Management in Rust

Use stack allocation when possible: Stack allocation is faster and doesn't require explicit deallocation.
Leverage Rust's ownership system: Let Rust's ownership and borrowing rules manage memory for you whenever possible.
Use appropriate data structures: Choose data structures that match your access patterns and memory requirements.
Consider custom allocators for specific use cases: If your application has unique memory requirements, consider implementing a custom allocator.
Profile your application: Use tools like valgrind or Rust-specific profilers to identify memory bottlenecks.
Avoid premature optimization: Focus on writing clear, idiomatic Rust code first. Optimize only when necessary and after profiling.
Use Box<T> for large objects or recursive data structures: This moves data to the heap, which can be more efficient for large objects.
Be mindful of lifetimes: Understand and use Rust's lifetime system to ensure references remain valid.
Utilize Rc<T> and Arc<T> judiciously: These types are useful for shared ownership but come with a performance cost.
Consider using arena allocators for short-lived objects: This can significantly reduce allocation overhead in some scenarios.

Conclusion

Memory management in Rust is a powerful feature that sets it apart from many other programming languages. By understanding and leveraging Rust's ownership model, borrowing rules, and allocation strategies, you can write efficient, safe, and performant code.

Remember that mastering memory management in Rust is a journey. The concepts we've covered here provide a solid foundation, but there's always more to learn. Don't hesitate to dive deeper into Rust's documentation, experiment with different allocation strategies, and engage with the Rust community to further enhance your understanding.

As you continue to work with Rust, you'll become more adept at managing memory efficiently. This will lead to robust, high-performance applications that are free from many common memory-related bugs.

Keep practicing, keep learning, and embrace the challenges – they're opportunities for growth.

Sources

Rust Diagnostic Attributes

Maksim Gritchin — Tue, 18 Jun 2024 20:53:11 +0000

Rust has introduced a powerful feature known as diagnostic attributes, which allows me to customise the error messages emitted by the compiler. This feature is particularly useful for improving the clarity of error messages, especially in complex scenarios involving traits and type mismatches.

Overview

The diagnostic attributes are part of a new built-in namespace, #[diagnostic], introduced in Rust 1.78. These attributes help provide more informative and context-specific error messages, making it easier for developers to understand and fix issues. Rust is known for its helpful error messages, but there are always cases where they can be improved. Crates that use the type system to verify invariants at compile time often generate large, unclear error messages when something goes wrong. Examples include Bevy, Axum, and Diesel. By giving crate authors tools to control the error messages emitted by the compiler, they can make these messages clearer and more helpful.

Key Features

Custom Error Messages: One of the main attributes in this namespace is #[diagnostic::on_unimplemented]. This attribute allows trait authors to specify custom error messages when a trait is required but not implemented for a type. For example, instead of a generic error message, you can provide a detailed explanation and hints on how to resolve the issue.
Non-Intrusive: The attributes in the #[diagnostic] namespace are designed to be non-intrusive. They do not affect the compilation result and are purely for enhancing the diagnostic output. This means that applying these attributes will not cause compilation errors as long as they are syntactically valid.
Compiler Flexibility: The compiler treats these diagnostic hints as optional. It may choose to ignore specific attributes or options, and the support for these attributes can change over time. However, the compiler must not change the semantics of an attribute or emit hard errors for malformed attributes.

Usage Example

Here is an example of how to use the #[diagnostic::on_unimplemented] attribute:

#[rustc_on_unimplemented(
message = "The type `{Self}` does not implement `MyTrait`. Please ensure that `{Self}` provides an implementation for `my_method`.",
note = "Implement the `my_method` function for `{Self}` to satisfy the `MyTrait` requirement.",
label = "missing implementation for `my_method`"
)]

trait MyTrait {
    fn my_method(&self);
}


struct MyType;

// Implement the trait for MyType
impl MyTrait for MyType {
    fn my_method(&self) {
        // Implementation goes here
    }
}

// another type that does not implement MyTrait
struct AnotherType;

// This will trigger the custom error message because AnotherType does not implement MyTrait
fn use_trait<T: MyTrait>(item: T) {
    item.my_method();
}

fn main() {
    let item = AnotherType;
    use_trait(item); // This line will cause a compile-time error with the custom message
}

In this example, attempting to use AnotherType with the use_trait function will trigger the custom error message because AnotherType does not implement MyTrait.

Benefits

Improved Developer Experience: By providing more specific and helpful error messages, developers can more quickly understand and resolve issues in their code.
Enhanced Code Clarity: Custom diagnostic messages can include additional context and explanations, making it easier to understand the requirements and constraints of your code.
Consistency: Collecting diagnostic attributes in a common namespace makes it easier for users to find and apply them, and for the language team to establish consistent rules and guidelines.

Conclusion

The introduction of diagnostic attributes in Rust represents a significant step forward in enhancing the developer experience. By allowing for customized and context-specific error messages, Rust continues to uphold its reputation for providing helpful and user-friendly compiler diagnostics. As you adopt these new features, you'll find that your code becomes not only more robust but also more accessible to others in the Rust community.

For more detailed information, you can refer to the official Rust documentation and the RFC that introduced this feature.

Sources

Writing Rust Documentation

Maksim Gritchin — Wed, 12 Jun 2024 13:49:30 +0000

Writing effective documentation is crucial for any programming language, and Rust is no exception. Good documentation helps users understand how to use your code, what it does, and why it matters. In this guide, I'll walk you through the best practices for writing documentation in Rust, ensuring that your code is not only functional but also accessible and user-friendly.

Introduction to Rust Documentation

Rust documentation is typically written using rustdoc, a tool that generates HTML documentation from comments in your source code. The primary goal of rustdoc is to make it easy for developers like you and me to document our code in a way that is both comprehensive and easy to understand.

Why Documentation Matters

Documentation serves several key purposes:

Communication: It explains what your code does, how it works, and how to use it.
Maintenance: It helps future developers (including yourself) understand the codebase, making it easier to maintain and extend.
Onboarding: It aids new team members in getting up to speed with the project.
Community: It allows the broader community to use and contribute to your project.

Writing Documentation in Rust

Commenting Your Code

Rust uses three types of comments for documentation:

Line comments: Start with // and are used for short, single-line comments.
Block comments: Enclosed in /* ... */ and can span multiple lines.
Doc comments: Start with /// for item-level documentation or //! for module-level documentation.

Item-Level Documentation

Item-level documentation comments (///) are used to describe functions, structs, enums, traits, and other items. These comments should be placed directly above the item they describe.

In this example, the add function is documented with a brief description and an example of how to use it. The # Examples section is a common convention in Rust documentation, providing a clear and concise way to demonstrate usage.

Module-Level Documentation

Module-level documentation comments (//!) are used to describe the overall purpose and functionality of a module. These comments should be placed at the top of the module file.

Here, the module-level comment provides a high-level overview of the module's purpose, while the item-level comments describe the individual functions.

Structuring Your Documentation

Good documentation is well-structured and easy to navigate. Here are some tips for structuring your Rust documentation:

Use Sections: Break your documentation into sections using headings. Common sections include # Examples, # Panics, # Errors, and # Safety.
Provide Examples: Examples are one of the most effective ways to demonstrate how to use your code. Include them wherever possible.
Explain Edge Cases: Document any edge cases or special conditions that users need to be aware of.
Link to Related Items: Use intra-doc links to connect related items within your documentation. This helps users navigate your documentation more easily.

Using Sections

Sections help organize your documentation and make it easier to read. Here are some common sections you might include:

Examples: Show how to use the item.
Panics: Describe any conditions under which the item might panic.
Errors: Explain any errors that might be returned.
Safety: For unsafe code, explain why it is safe to use.

In this example, the divide function documentation includes an # Examples section to show how to use the function and a # Panics section to describe a condition that will cause the function to panic.

Providing Examples

Examples are crucial for helping users understand how to use your code. They should be simple, clear, and demonstrate the most common use cases.

This example shows how to calculate the factorial of a number, providing a clear and concise example of how to use the factorial function.

Explaining Edge Cases

Edge cases are situations that occur outside of normal operating conditions. Documenting these cases helps users understand how your code behaves in less common scenarios.

In this example, the fibonacci function documentation includes a # Panics section to explain that the function will panic if the input is too large.

Linking to Related Items

Intra-doc links allow you to create hyperlinks to other items within your documentation. This helps users navigate your documentation more easily.

In this example, the add and subtract functions link to each other using intra-doc links, making it easy for users to navigate between related items.

Using the `#[doc]` Attribute

The #[doc] attribute in Rust provides additional flexibility for writing documentation. You can use it to add documentation to items in a more programmatic way. This attribute is particularly useful when you need to generate documentation dynamically or when you want to include documentation that isn't directly tied to a specific item.

Basic Usage

The #[doc] attribute can be used to add documentation to any item. Here's a simple example:

#[doc = "Adds two numbers together."] 
fn add(a: i32, b: i32) -> i32 { a + b }

This is equivalent to using the /// comment style but allows for more complex scenarios.

Including External Files

You can use the #[doc] attribute to include documentation from external files. This is useful if you have large blocks of documentation that you want to keep separate from your code.

#[doc = include_str!("docs/add_function.md")] 
fn add(a: i32, b: i32) -> i32 { a + b }

In this example, the documentation for the add function is included from an external Markdown file.

Conditional Documentation

The #[doc] attribute can also be used to conditionally include documentation based on compile-time conditions. This is useful for documenting platform-specific behavior or features.

#[cfg(target_os = "windows")] 
#[doc = "This function is only available on Windows."] 
fn windows_only_function() { // Windows-specific code } 

#[cfg(target_os = "linux")] 
#[doc = "This function is only available on Linux."] 
fn linux_only_function() { // Linux-specific code }

In this example, different documentation is included based on the target operating system.

Best Practices for Writing Documentation

Here are some best practices to keep in mind when writing Rust documentation:

Be Clear and Concise: Write in a clear and concise manner. Avoid unnecessary jargon and keep sentences short and to the point.
Use Proper Grammar and Spelling: Ensure your documentation is free of grammatical and spelling errors. This helps maintain a professional appearance.
Be Consistent: Use consistent terminology and formatting throughout your documentation. This makes it easier for users to understand and follow.
Keep It Up to Date: Regularly update your documentation to reflect changes in your code. Outdated documentation can be more harmful than no documentation at all.
Use Code Examples: Include code examples wherever possible. They are one of the most effective ways to demonstrate how to use your code.
Document All Public Items: Ensure that all public items (functions, structs, enums, etc.) are documented. This helps users understand how to use your library or application.

Example of Comprehensive Documentation

Let's put it all together with a comprehensive example:

In this example, the module-level comment provides an overview of the module, and each function is documented with a description, examples, and any relevant panics.

Documentation Tests

One of the powerful features of Rust's documentation system is the ability to include tests directly within your documentation comments. These are known as documentation tests, and they serve a dual purpose: they provide examples of how to use your code and ensure that the examples remain correct as your code evolves.

Writing Documentation Tests

To write a documentation test, you simply include code examples within triple backticks in your doc comments. Rust's rustdoc tool will automatically extract these examples and run them as tests when you run cargo test.

Here's a basic example:

In this example, the code within the triple backticks is a documentation test. When you run cargo test, this code will be compiled and executed to ensure that it produces the expected result.

Benefits of Documentation Tests

Ensuring Accuracy: Documentation tests ensure that your examples are always accurate and up-to-date. If you change your code in a way that breaks an example, the test will fail, alerting you to the issue.
Providing Working Examples: Users can trust that the examples in your documentation actually work, as they are tested alongside your code.
Reducing Maintenance: By embedding tests in your documentation, you reduce the need for separate example code files, making it easier to maintain consistency between your code and its documentation.

Advanced Usage

You can also include multiple examples and more complex scenarios in your documentation tests. Additionally, you can use attributes to control the behavior of these tests.

For instance, you might want to ignore certain tests or only run them under specific conditions:

In this example, the second test is ignored because it demonstrates a panic scenario. You can use the ignore attribute to prevent certain tests from running by default.

Running Documentation Tests

To run your documentation tests, simply use the cargo test command. This will compile and run all tests, including those embedded in your documentation comments.

cargo test

By incorporating documentation tests into your workflow, you can ensure that your documentation remains accurate and useful, providing real value to users of your code.

Conclusion

Writing good documentation is an essential skill for any Rust developer. By following the best practices outlined in this guide, you can create documentation that is clear, concise, and helpful to your users. Remember to use rustdoc to generate your documentation, and keep it up to date as your code evolves. With well-written documentation, you can make your code more accessible, maintainable, and enjoyable to use.

Sources

Rust Book

Forem: Maksim Gritchin

Memory Allocations in Rust

Introduction

Memory Layout Basics

Executable Binary Structure

ELF Executable Structure

ELF File Structure

Key Points

Runtime Memory Layout

Stack vs Heap

Stack

Heap

Function Stack Frames

Rust's Approach to Memory Management

Ownership Rules

General Ownership Rules

Exceptions and Special Cases

Borrowing

Data Types and Memory Allocation

Primitive Data Types

Categories of Primitive Types

The Copy Trait

Storage Location

Memory Layout

Compound Data Types

Array

Tuples

Structs

Enums

Dynamic Data Types

Vector

Slice

String

Stack Allocation in Rust

Key Points:

Memory Allocators in Rust

Standard Allocator

jemalloc

Microsoft's mimalloc

Advanced Memory Management Techniques

Using Box<T> for Heap Allocation

Reference Counting with Rc<T>

Atomic Reference Counting with Arc<T>

Optimising Memory Usage

Struct Layout

Copy vs Clone

Option Type Optimization

Advanced Concepts

Memory Pages and Virtual Memory

Resident Set Size (RSS) vs Virtual Memory

Tuning jemalloc

Best Practices for Memory Management in Rust

Conclusion

Sources

Rust Diagnostic Attributes

Overview

Key Features

Usage Example

Benefits

Conclusion

Sources

Writing Rust Documentation

Introduction to Rust Documentation

Why Documentation Matters

Writing Documentation in Rust

Commenting Your Code

Item-Level Documentation

Module-Level Documentation

Structuring Your Documentation

Using Sections

Providing Examples

Explaining Edge Cases

Linking to Related Items

Using the #[doc] Attribute

Basic Usage

Including External Files

Conditional Documentation

Best Practices for Writing Documentation

Example of Comprehensive Documentation

Documentation Tests

The `Copy` Trait

Using `Box<T>` for Heap Allocation

Reference Counting with `Rc<T>`

Atomic Reference Counting with `Arc<T>`

Using the `#[doc]` Attribute