CS Float Representation

Golang Graceful Shutdown

Rust's Cell<T>

Copy or Move?

Rust PartialEq, Eq, PartialOrd and Ord

Rust Raw Pointers

rust

golang

---
title: 'CS Float Representation'
tags: ['cs', 'rust']
published_date: '2025-02-20'
description: 'Learn about the representation of floating-point numbers in computer science.'
---


### Notation & Number Bases
- `_2` denotes numbers **in base 2 (binary)**.
- `_10` denotes numbers **in base 10 (decimal)**.

For example:
- `13_10` means thirteen in decimal.
- `1101_2` means the binary number “1101.”

## Decimal Normalization (Scientific Notation)

In decimal scientific notation, we represent a number so that there is only one nonzero digit to the left of the decimal point. This “normalized” form looks like this:

$$
Number=Sign×Mantissa×10^{Exponent}
$$

#### Examples:
- `13_10` can be written as: (We moved the decimal point 1 place to the left.)

$$ 1.3 \times 10^1 $$

- `1500_10` can be written as: (We moved the decimal point 3 places to the left.)

$$ 1.5 \times 10^3 $$

### Moving the Decimal Point with Powers of 10
- Positive Exponent: $$4.2 \times 10^3$$ means move the decimal point 3 places to the right: $$4200$$.
- Negative Exponent: $$4.2 \times 10^{-3}$$ means move the decimal point 3 places to the left: $$0.0042$$.

### The general rule for positive and negative exponents of 10:
- Positive exponents:

$$ (10^n, n > 0): 10^n = \underbrace{10 \times 10 \times \cdots \times 10}_{n \text{ times}} $$

- Negative exponents:

$$ (10^{-n}, n > 0): 10^{-n} = \frac{1}{10^n} = \frac{1}{\underbrace{10 \times 10 \times \cdots \times 10}_{n \text{ times}}} $$

OR

$$ (10^{-n}, n > 0): 10^{-n} = \frac{1}{10} * \frac{1}{10 } * .... \frac{1}{n}  $$

### Binary Normalization & Its Relation to Scientific Notation

Floating‑point numbers in computers work similarly to scientific notation—but in base 2. In binary, normalized numbers are written as:

$$ 1.(fraction \space bits)  ×2 ^{Exponent} $$

#### Key Points:
- **Normalized Form (Binary):**
There is always **one nonzero digit** to the left of the binary point. In binary, that digit is always **1** (except for special cases called subnormals).

- **Implicit Leading 1:**
Because the leftmost digit in any normalized binary number is always **1**, it is not stored. This “hidden bit” saves space and improves precision.

#### Example:
- The number `13_10` in binary is `1101_2`. Normalizing it: 

$$ 1101_2  = 1.101 _2 × 2 ^3 $$

**Notice that the “1” before the binary point is implicit when stored.**

### Components of a Floating-Point Number

An IEEE 754 floating‑point number (e.g., in 32‑bit single precision) is divided into three main parts:
1. Sign Bit (1 bit):
	- 0 means positive.
	- 1 means negative.
2. Exponent Field (k bits):
	- Stored as an unsigned integer.
	- Uses a bias to allow for both positive and negative exponents.
3. Mantissa (Significand) (remaining bits):
	- Contains the fractional part of the normalized number.
	- The implicit leading “1” is not stored for normalized numbers.

### Understanding the Bias

#### Why Use a Bias?
- **Problem:** Exponents can be positive or negative (e.g., `2^3` or `2^-5`). However, hardware prefers to work with **unsigned integers**.
- **Solution:** Add a fixed bias to the actual exponent to store it as an unsigned number.

#### Bias Formula:
where `k` is the number of exponent bits.

$$ Bias = 2^{(k-1)} - 1 $$

- **For 32-bit floats** (k = 8): Bias = `2^7 - 1 = 127`
- **For 64-bit floats** (k = 11): Bias = `2^10 - 1 = 1023`

#### How It Works:
- **Storing:** `Store Exponent = Actual Exponent + Bias`
- **Retrieving:** `Store Exponent = Actual Exponent - Bias`

#### Example:
- If the actual exponent is `3` (in single precision), the stored exponent is: `3 + 127 = 130`
- If we read a stored exponent of `120`, then the actual exponent is: `120 - 127 = -7`

#### How Does the Bias Help with Comparisons?

Because each exponent value is stored as a non-negative (biased) integer, we can compare exponents by simply comparing their stored (unsigned) integer representations—provided the sign bit for the whole floating-point number is the same.

**Key idea:** If we keep the number format in [sign | exponent + bias | fraction], then for two positive floating-point numbers:
- If the stored exponent of AAA is greater than the stored exponent of BBB, then A>BA > BA>B, regardless of the fraction (assuming both are normalized and not edge cases like NaN or infinity).
- If the stored exponent of AAA equals the stored exponent of BBB, then comparing the fraction bits determines which is bigger.

Hence, hardware can do much simpler comparisons by treating the exponent field as an unsigned magnitude. We avoid messing around with a separate sign bit for the exponent, and the ordering of floats becomes more straightforward under typical cases.

### Why the Mantissa Always Starts with 1
- **Normalization:** In binary, to have only one nonzero digit to the left of the binary point, we adjust the number so it is always in the form: 

$$ 1.xxxxx_2  × 2^{Exponent} $$

- **Storage Efficiency:** Since the leading digit is always 1 (in normalized numbers), it does not need to be stored. This saves one bit and allows more bits to be used for the fraction.
- **Exception:** Subnormal Numbers When the exponent field is all zeros, the number is too small to be normalized. In this case, the leading digit is 0 instead of 1.


### Converting Between Numbers and IEEE 754 Representation

Let’s walk through two detailed examples.

#### Example A: Converting 13.25 to IEEE 754 Single Precision

#### A.1. Convert 13.25 to Binary
1. Integer Part (13): $$ 13_{10} = 1101_2 $$
2. Fractional Part (0.25): Use the “multiply-by‑2” method:
	- 0.25 x 2 = 0.5 => Bit: 0  because 0.5 < 1 
	- 0.5 x 2 = 1.0 => Bit: 1  (since we reached 1, subtract 1 and continue; here, remainder becomes 0)
	- So, $$ 0.25_{10} = 0.01_2 $$
3. Combine: $$ 13.25_{10} = 1101.01_2 $$

#### A.2. Normalize the Binary Number
Normalize to the form $$ 1.fraction \times 2^{Exponent} $$

$$ 1101.01_2 = 1.10101 \times 2^3 $$

Normalized significand: $$ 1.10101 $$ And Actual exponent: $$ 3 $$

#### A.3. Determine the IEEE 754 Fields

1. **Sign Bit:** `13.25` is positive → `Sign = 0`.
2. **Exponent Field:**
	- Actual exponent = `3`
	- Bias (for single precision) = `127`
	- Stored Exponent = `3 + 127 = 130` in binary (8 bits): $$ 10000010_2 $$

3. **Mantissa (Fraction) Field:**
- From normalized significand: $$ 1.10101 $$
- Stored mantissa = bits after the 1.  = $$ 10101 $$
- The mantissa field is 23 bits, so pad with zeros: $$ 101010000…_2 $$

#### A.4. Final IEEE 754 Single Precision Representation

Combine the fields:
- **Sign:** $$ 0 $$
- **Exponent:** $$ 10000010 $$
- **Mantissa:** $$ 10101000000000000000000 $$
Final 32-bit representation: $$ 0 10000010 10101000000000000000000 $$

#### A.5. Converting Back from Binary to Number

Extract the Fields:
- **Sign:** $$ 0 $$ → positive
- **Exponent field:** $$ 10000010_2 = 130_{10} $$ => Actual exponent = $$ 130 - 127 = 3 $$ 
- **Mantissa:** $$ 10101 $$ (plus 18 zeros) → Normalized significand = $$ 1.10101_2 $$ 

Compute the Value:

$$ Value = (+1) × (1.10101_2 ) × 2 ^3 $$

So Converting $$ 1.10101_2 $$  to decimal gives $$ 1.65625 $$ , and multiplying by $$ 2^3 $$  = $$ 8 $$ yields $$ 13.25 $$ .

To convert the binary number $$ 1.10101_2 $$  to its decimal equivalent $$ 1.65625_10 $$ , we can perform two different operations:

#### Method 1: Weighted Sum (Bit-by-Bit) Method

1. Write the number as $$ 1.10101_2 $$ . Separate it into the integer part and the fractional part.
2. The integer part $$ 1 $$  is simply $$ 1 × 2^0 = 1 $$ .
3. For the fractional part $$ 10101 $$ :
	- The first digit after the point ($$ 1 $$) represents $$ 1 × 2^-1 = 0.5 $$ .
	- The second digit ($$ 0 $$) represents $$ 0 × 2^-2 = 0. $$ 
	- The third digit ($$ 1 $$) represents $$ 1 × 2^-3 = 0.125 $$ .
	- The fourth digit ($$ 0 $$) represents $$ 0 × 2^-4 = 0. $$ 
	- The fifth digit ($$ 1 $$) represents $$ 1 × 2^-5 = 0.03125 $$ .

4. Add these contributions together:
$$ 1 (integer \space part) + 0.5 + 0 + 0.125 + 0 + 0.03125 = 1.65625 $$ .

#### Method 2: Arithmetic Division Method

1. Write the number as $$ 1.10101_2 $$ , where the fractional part is $$ 10101 $$ .
2. Convert the fractional part $$ 10101 $$  directly from binary to decimal as an integer:
	- $$ 10101_2  = (1×2^4) + (0×2^3) + (1×2^2) + (0×2^1) + (1×2^0) = 16 + 0 + 4 + 0 + 1 = 21 $$ .
3. Count the number of digits in the fractional part. Here, there are 5  digits, so the denominator will be $$ 2^5 = 32 $$ .
4. Compute the fractional value by dividing the integer (21) by 32: $$ 21 ÷ 32 = 0.65625 $$ .
5. Add the integer part (which is 1) to this fraction: $$ 1 + 0.65625 = 1.65625 $$ .

Both methods show that $$ 1.10101_2 $$  equals $$ 1.65625_10 $$  in decimal.

### Rust Code Example: 

```rust

/// A structure that decomposes a 32-bit floating-point number (f32)
/// into its sign, exponent, and mantissa components.
#[derive(Debug, Clone, Copy)]
pub struct FloatRepr {
    /// `true` if the number is negative.
    sign: bool,
    /// The raw 8-bit exponent (stored with a bias of 127).
    exponent: u8,
    /// The raw 23-bit mantissa (fractional part).
    mantissa: u32,
}

impl FloatRepr {
    /// Constructs a `FloatRepr` from an `f32` value by extracting its underlying bit fields.
    ///
    /// # Details
    /// - The sign is the most significant bit.
    /// - The next 8 bits represent the exponent (with a bias of 127).
    /// - The remaining 23 bits represent the mantissa.
    pub fn from_f32(value: f32) -> Self {
        let bits = value.to_bits();
        let sign = (bits >> 31) != 0;
        let exponent = ((bits >> 23) & 0xFF) as u8;
        let mantissa = bits & 0x7FFFFF; // 23 bits
        Self {
            sign,
            exponent,
            mantissa,
        }
    }

    /// Returns the unbiased exponent.
    ///
    /// The exponent in IEEE 754 format is stored with a bias of 127.
    /// Subtracting 127 yields the actual exponent.
    pub fn unbiased_exponent(&self) -> i32 {
        self.exponent as i32 - 127
    }

    /// Computes the fractional part of the mantissa using arithmetic division.
    ///
    /// The mantissa is stored as a 23-bit integer representing the fractional part.
    /// Dividing by 2²³ normalizes it to the range [0, 1).
    ///
    /// # Note
    /// For normalized numbers, the full significand is `1 + mantissa_fraction()`.
    pub fn mantissa_fraction_arithmetic(&self) -> f32 {
        // 1 << 23 is equivalent to 2^23, it is a bitwise left shift operation
        self.mantissa as f32 / (1 << 23) as f32
    }

    /// Computes the fractional part of the mantissa using a weighted bit-by-bit summation.
    ///
    /// This method iterates over each bit (0 to 22) of the 23-bit mantissa.
    /// Each bit at position `i` represents a fraction with weight 2^(i - 23),
    /// meaning that the least-significant bit (position 0) has a weight of 2^(-23)
    /// and the most significant bit (position 22) has a weight of 2^(-1).
    ///
    /// For each bit position, we test if the bit is set (i.e. equals 1).
    /// The expression `(self.mantissa >> i) & 1 == 1` does that:
    /// - `self.mantissa >> i` shifts the mantissa right by `i` bits, moving the i-th bit to the rightmost position.
    /// - `& 1` masks all other bits, isolating just that least significant bit.
    /// - We then compare the result with 1. If the result is 1, then bit at position `i` was set.
    ///
    /// The weighted contribution for that bit if it is set is computed as 2^(i - 23)
    /// and added to the running total. In the end, the sum of all contributions represents
    /// the decoded fractional part of the mantissa.
    pub fn mantissa_fraction_weighted(&self) -> f32 {
        let mut result = 0.0;
        for i in 0..23 {
            if (self.mantissa >> i) & 1 == 1 {
                // If the bit is set, we add its fractional contribution
                result += 2f32.powf(i as f32 - 23.0);
            }
        }
        result
    }
}
```

#### Methods:
The methods mantissa_fraction_arithmetic and mantissa_fraction_weighted implement two equivalent techniques to convert the mantissa back to its fractional decimal form, and we leverage some bitwise magic. These functions reflect the methods described earlier in the notes.

- The `mantissa_fraction_arithmetic` :
	- **Conciseness:** A single, clear arithmetic expression.
	- **Efficiency:** Likely optimized by the compiler and directly mapped to a hardware division.
	- **Readability:** It directly maps the mathematical operation, making it easier to grasp once we're familiar with the theory.
- The `mantissa_fraction_weighted`  :
	- **Educational Value:** It clearly shows the bit-level contributions to the overall fraction, which can help in understanding how binary fractions work.
	- **Explicitness:** We see the logic behind the summation of weighted bits.
	- **Verbosity:** It takes several lines and a loop to achieve what one arithmetic division does.
	- **Performance:** The loop and conditional checks can be less efficient compared to a single division.
	- **Bitwise visualization help:**

```text
Mantissa: 0b101 (5 in decimal)
Bit positions: [2][1][0]

i=0 (weight 2^-3 = 0.125)
┌───────────────┐
│Shift right 0: 101 │ → LSB=1 → add 0.125
└───────────────┘

i=1 (weight 2^-2 = 0.25)
┌───────────────┐
│Shift right 1: 10  │ → LSB=0 → no addition
└───────────────┘

i=2 (weight 2^-1 = 0.5)
┌───────────────┐
│Shift right 2: 1   │ → LSB=1 → add 0.5
└───────────────┘

Total: 0.125 + 0.5 = 0.625 (equivalent to 5/8)
```

### Some considerations:

- **IEEE 754 Standard:**
Defines the format for 32‑bit (single precision) and 64‑bit (double precision) floats, as well as special values such as NaN (Not a Number), ±Infinity, and ±0.
- **Subnormal (Denormal) Numbers:**
When the exponent field is all zeros, numbers are too small to be normalized. In these cases, the leading bit is assumed to be 0, which allows representation of values very close to zero.
- **Precision Limitations:**
Not all decimal numbers can be exactly represented in binary (e.g., 0.1 is repeating in binary). This leads to rounding errors in arithmetic operations.
- **Range vs. Precision:**
	- More exponent bits → Wider range of representable numbers.
	- More mantissa bits → Higher precision (more exact fractional representation).
- **Common Pitfalls:**
	- Avoid direct equality checks with floats (e.g., instead of if a == b, use a tolerance check like abs(a - b) < 1e-6).
	- Be aware of rounding errors when converting between decimal and binary.


### Resources
- https://www.youtube.com/watch?v=PZRI1IfStY0
- https://www.youtube.com/watch?v=bbkcEiUjehk
- https://www.youtube.com/watch?v=bFLchKMm6YA


Learn about the representation of floating-point numbers in computer science.

---
title: "Golang Graceful Shutdown"
id: golang-shutdown
tags: ["golang"]
published_date: "2025-02-20"
description: "Learn about Golang's graceful shutdown."
---

When building resilient Go applications, handling graceful shutdown is a must. The goal is to let our server finish processing in-flight requests and cleanly release any resources (like database connections or caches) before our application fully terminates. 

## Full code example:

```go
func run() error {
	// Initialize resources (e.g., database, cache, etc.)
	// For demonstration, we just set up a simple HTTP server.
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello!"))
	})

	server := http.Server{
		Addr:    ":80",
		Handler: mux,
		// Configure timeouts according to our application needs.
		ReadTimeout:       5 * time.Second,
		WriteTimeout:      10 * time.Second,
		IdleTimeout:       30 * time.Second,
		ReadHeaderTimeout: 2 * time.Second,
	}

	// Create a context that listens for termination signals.
	// This context will be canceled when one of the specified signals is received.
	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
	defer stop()

	// Channel to capture server errors
	errCh := make(chan error, 1)

	// Start the server in a separate goroutine.
	go func() {
		log.Printf("HTTP server starting on %s", server.Addr)
		// ListenAndServe will return http.ErrServerClosed on graceful shutdown.
		errCh <- server.ListenAndServe()
	}()

	var err error

	// Wait for either a server error or a shutdown signal.
	select {
	case err = <-errCh:
		// An error occurred while running the server.
	case <-ctx.Done():
		// A termination signal was received.
		log.Printf("Shutdown signal was received")
	}

	// Create a context with a timeout for the graceful shutdown process.
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	log.Println("Initiating graceful shutdown...")
	// Shutdown the server
	if shutdownErr := server.Shutdown(shutdownCtx); shutdownErr != nil {
		// Merge the server error with the shutdown error. ie if the net.listener.Accept() returns an error.
		return errors.Join(err, shutdownErr)
	}

	// Clean up other resources (e.g., database, cache, etc.)  
	// In many cases, if we are working in an API, all the other resources are consumed by our HTTP handlers, so we should shut down the server first to stop accepting new requests, and then clean up the resources.  
	// This way, our in-flight requests will still have access to the resources they need.

	return err
}
```

##  Here’s a breakdown of  the approach:

### Catching Termination Signals

Using `signal.NotifyContext`, we create a context that cancels as soon as a termination signal (like `SIGINT`, `SIGTERM`, etc.) is received. This allows the application to start a graceful shutdown process immediately.

```go
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
defer stop()
```

### Starting the Server in a Goroutine and Monitoring for Errors

The server runs concurrently, and any error (including `http.ErrServerClosed` on a graceful shutdown) is sent over a channel so that the main goroutine can react accordingly.

```go
errCh := make(chan error, 1)
go func() {
    log.Printf("HTTP server starting on %s", server.Addr)
    errCh <- server.ListenAndServe()
}()
```

### Waiting

We wait for either an error from the server or a cancellation of the context (indicating that a termination signal was received). This select block is the heart of the graceful shutdown logic.

```go
var err error
select {
case err = <-errCh:
    // An error occurred while running the server.
case <-ctx.Done():
    log.Printf("Shutdown signal was received")
}
```

### Shutting Down the HTTP Server First

It is crucial to shut down the HTTP server before cleaning up other resources. By doing so, we prevent new requests from being accepted while still allowing **in-flight requests** to complete. This ensures that the cleanup of dependent resources (e.g., `databases`, `caches`) does not interrupt ongoing operations that still rely on them.

Anti-pattern: Closing databases first → panics in in-flight handlers.

```go
shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

log.Println("Initiating graceful shutdown...")
if shutdownErr := server.Shutdown(shutdownCtx); shutdownErr != nil {
    return errors.Join(err, shutdownErr)
}

// Clean up other resources (e.g., database, cache, etc.) 
```

### On Context Management: Why Not to Use the Signal Context as the Base Context

While it might be tempting to use the context returned by `signal.NotifyContext` as our application `context`, doing so can lead to unintended cancellation of **in-flight requests**. The signal context is specifically designed to trigger the shutdown sequence—when a termination signal is received, the context is cancelled immediately. If this same context is used for initializing services and handling business logic, the cancellation might propagate to parts of our application that should remain active until a **graceful shutdown** is fully in progress.

```go
ctx := context.Background()
services := services.New(ctx)
repository := repository.New(ctx)
```
Using separate contexts—one for our application's core operations and one for handling termination signals—ensures that our application can manage shutdowns gracefully without sacrificing the integrity or completion of ongoing processes.

### Logging Specific Signals with signal.Notify

In scenarios where it’s necessary to log or handle the specific signal received (for instance, tracking if `Kubernetes` is killing our application), using `signal.Notify` instead of `signal.NotifyContext` provides more granular control:

```go
sigquit := make(chan os.Signal, 1)
signal.Notify(sigquit, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
// ...
select {
case err = <-errCh:
    // Handle server error
case sig := <-sigquit:
    log.Printf("Caught signal: %v", sig)
}
```

So use `signal.Notify` (vs `NotifyContext`) when we need:
- Logging specific signals (e.g., `SIGTERM` vs `SIGQUIT`).
- Custom handling for signals (e.g., `SIGHUP` for config reload).

Note that, as of now, `signal.NotifyContext` does not provide the specific signal received—which is why this approach can be useful for detailed logging.





---
title: "Rust's Cell<T>"
id: rust-cell
tags: ["rust"]
connections: ["rust", "rust-copy-or-move", "rust-raw-pointers"]
published_date: "2025-02-20"
description: "Learn about Rust's Cell<T>."
---

Cell\<T\> is a type in Rust’s standard library `std::cell::Cell` that provides interior mutability—a technique that allows us to change data even when we only have an immutable reference `&T` to its container. It does so while preserving Rust’s strict safety guarantees.

### How Cell Achieves Interior Mutability

Cell\<T\> implements interior mutability by moving values in and out of the cell. In particular:
- **No Direct Mutable References**: We can never obtain an &mut T to the inner value.
- **Value Extraction by Replacement**: The value inside a Cell cannot be directly extracted; it must be replaced with another value.

These constraints ensure that there is never more than one reference to the inner value at any given time.

### Provided Methods

For all types T, Cell\<T\> offers:
- **replace**: Replaces the current interior value with a new one and returns the old value.
- **into_inner**: Consumes the Cell\<T\> and returns the inner value.
- **set**: Replaces the interior value (dropping the old one).
For types that implement Copy:
- **get**: Retrieves the current value by copying it.
For types that implement Default:
- **take**: Replaces the current value with Default::default() and returns the old value.

### When to Use Cell
1. Mutable Fields in Immutable Structs
We can have a field that can change even when the struct is not declared as mutable:

```rust
use std::cell::Cell;

struct Counter {
    count: Cell<u32>,
}

impl Counter {
    fn increment(&self) {
        self.count.set(self.count.get() + 1);
    }
}
```
2. Thread-Local Data
Since Cell\<T\> is not thread-safe (i.e., it does not implement Sync), it’s ideal for single-threaded scenarios.
3. Optimizing Performance
Use it for small, copyable data (e.g., integers or booleans) to avoid runtime borrow checks. For larger or non- Copy types, we should consider using RefCell.
4. No Runtime Overhead: Cell enforces safety at compile time, so there are no runtime checks (unlike RefCell\<T\>).

### Limitations
1. **No Direct References**:
We cannot obtain a direct reference ( &T or &mut T) to the inner data. Instead, we must work with methods like get, set, replace, or take.
2. **Not Thread-Safe**:
Since Cell\<T\> is designed for single-threaded usage, we must use other synchronization primitives (e.g., Mutex or atomic types) for cross-thread shared mutability.

### Examples

With **Copy Types**:

```rust
use std::cell::Cell;
struct MyStruct {
	x: i32,
	y: Cell<i32>,
}

let s = MyStruct {
	x: 42,
	y: Cell::new(42),
};

s.y.set(100); // Mutation allowed, even though `s` isn't declared as `mut`    
assert_eq!(s.y.get(), 100);
    // s.x = 100; // Error: cannot assign to `s.x`, as `s` is not declared as `mut
````

With **Non-Copy Types**:

```rust
use std::cell::Cell;
let cell = Cell::new(String::from("Hello"));
// As `String` is not `Copy`, we can't get the value out of the cell with `get`
// For non-copy types, we can use `replace` to swap the value with a new one and get the old value
let old = cell.replace(String::from("World"));
assert_eq!(old, "Hello");
// Or we can use `take` to get the value and replace it with the default value
let old = cell.take();
assert_eq!(old, "World");
// We can also use `into_inner` to get the value and consume the cell and as we used `take` before, the value should be the default value        
assert_eq!(cell.into_inner(), "");
```

### How It Works

- Cell internally uses UnsafeCell (the backbone of interior mutability in Rust) but provides a safe API.
- It ensures safety by:
	1. Disallowing references to the inner value (prevents aliasing).
	2. Allowing mutation only through methods that copy or replace the entire value.

### UnsafeCell Explained Simply

is the low-level building block for Rust’s interior mutability. It allows us to mutate data even through an immutable reference ( &T), but it requires manual safety guarantees from us. Think of it as a "backdoor" to bypass Rust’s default borrowing rules, with the caveat that we are responsible for ensuring safety.

### The `get_mut` Method in Cell

Cell\<T\> in Rust provides a method called get_mut(&mut self) -> &mut T, which allows obtaining a mutable reference to the inner value. This method requires a mutable reference to the Cell itself (&mut self) for several reasons:
1. **Exclusive Access**: By requiring &mut self, Rust ensures that we have exclusive access to the cell, meaning no other references (mutable or immutable) exist while we're modifying it through get_mut. This aligns with Rust's borrow checker rules, preventing data races or inconsistencies.
2. **Compile-Time Safety**: The requirement of &mut self allows the compiler to enforce safety guarantees at compile time. It ensures that there are no other references alive when we call get_mut, which is crucial because shared references assume immutability during their lifetime.
The primary purpose of Cell  is interior mutability without holding onto references, typically by moving or copying values in and out. Methods like set  and replace  modify the cell without providing direct access through immutable references. The presence of get_mut  facilitates scenarios where unique access is guaranteed, making it easier to work with cells when needed. So, Cell::get_mut  takes &mut self,  meaning it can only be called when we have a &mut Cell  reference, which is a bit atypical.

## Custom Cell Implementation

The following implementation provides a minimal version of interior mutability similar to `std::cell::Cell` by leveraging UnsafeCell\<T\>.

```rust
use std::cell::UnsafeCell;

struct MyCell<T> {
    value: UnsafeCell<T>,
}

impl<T> MyCell<T> {
    fn new(value: T) -> MyCell<T> {
        Self {
            value: UnsafeCell::new(value),
        }
    }

    fn set_direct(&self, value: T) {
        // SAFETY: MyCell is not Sync, so no other thread can access this value.
        // Also, because we never expose references to the inner value, this direct
        // mutation is safe.
        unsafe {
            // we get a raw pointer to the inner value
            let ptr = self.value.get();
            // we can dereference the pointer and change the value
            *ptr = value;
        }
    }

    fn set(&self, value: T) {
        self.replace(value);
    }

    fn replace(&self, value: T) -> T {
        // SAFETY: MyCell is not Sync, so no other thread can access this value.
        // Also, because we never expose references to the inner value, this replacement is safe.
        std::mem::replace(unsafe { &mut *self.value.get() }, value)
    }

    fn into_inner(self) -> T {
        self.value.into_inner()
    }
}

impl<T: Copy> MyCell<T> {
    fn get(&self) -> T {
        // SAFETY: MyCell is not Sync, so we can assume that no other thread is accessing the value
        // and as we are using Copy types, we can safely return the value because it's a copy not a reference
        unsafe { *self.value.get() }
    }
}

impl<T: Default> MyCell<T> {
    fn take(&self) -> T {
        self.replace(Default::default())
    }
}
```

- **Thread Safety**: By not implementing Sync, we enforce single-threaded usage, mirroring Cell\<T\>'s behavior.
- **No Direct References**: Never expose `&T` or `&mut T` from MyCell.
- **Copy Restriction for get**: By restricting get() to Copy types and avoiding reference leaks, we sidestep Rust’s usual borrowing rules. Mutation is safe because there’s no way to observe invalid states via references.
- **No Runtime Overhead**: Like Cell\<T\>, this implementation avoids runtime checks (e.g., no borrow counters like `RefCell`).

### How do `set_direct` and `get` work?

Both methods use [raw pointers]() under the hood to access and manipulate the data stored in the `UnsafeCell`. The key idea is that the raw pointer gives us direct access to the memory where the value of type `T` is stored.
Obtaining the Raw Pointer: Both `set_direct` and `get` begin by calling `self.value.get()`. This method returns a raw mutable pointer `( *mut T)` to the inner data.

- **Representation**:
The raw pointer is essentially just a memory address (or a fat pointer with extra metadata for unsized types), meaning it directly points to the location in memory where the value is stored.

**set_direct Method**:
- In set_direct, after obtaining the raw pointer, we dereference it using `*ptr`. This operation accesses the memory location directly. The assignment (`ptr = value;`) then writes the new value into that location.
- The old value is overwritten. If `T` implements `Drop`, its destructor will be called automatically as part of the assignment process, ensuring that the old value’s resources are properly released.

**Understanding the Components**

- **self.value**: This is an instance of UnsafeCell\<T\>.
- **The get Method**: Calling `self.value.get()` returns a raw mutable pointer of type `*mut T` that points to the inner value. This method is marked as safe to call, but the raw pointer it produces does not come with any of Rust’s usual aliasing or mutability guarantees. Because of that, we must use an unsafe block when dereferencing it.
- **Dereferencing with '*'**: The `*` operator is used to dereference the raw pointer. The expression  `*self.value.get()` accesses the memory location where the inner value of the UnsafeCell is stored.

The `get` Method **(for T: Copy)**:
-  Similarly, `get` obtains the raw pointer via `self.value.get()` and dereferences it with `*self.value.get()`. Since the method returns a value of type `T` and `T` implements `Copy`, the data at that memory address is copied (using the layout of `T`) and returned.
- The bytes at that address represent the value of type `T`. Dereferencing the pointer retrieves these bytes, effectively reconstructing the value according to its type's layout so dereferencing interprets these bytes as a valid instance of `T`.

### Why the Copy Trait Matters in get
**Copy vs. Move**:
For types that implement the `Copy` trait, this dereference produces a copy of the value. That means the original value remains intact inside the `cell`, and we get a duplicate of it.
For types that do not implement `Copy`, dereferencing would attempt to move the value. Moving would mean transferring ownership of the value out of the cell, which is problematic here because:
- **Ownership Violation**: The value is still stored inside the cell, and moving it out would leave the cell with an uninitialized or invalid value. This violates Rust’s ownership rules, which ensure that each piece of data has a single owner at any given time. It would leave the original location in an invalid state while it’s still accessible by its original owner.
- **Potential for Double Drop**: If we moved the value, when the cell is later dropped, it might try to drop an already-moved (and thus uninitialized) value, leading to undefined behavior.

So, by requiring `T: Copy`, we guarantee that dereferencing produces a copy (and not a move), making it safe to return the value without affecting the stored data. 


Gist: https://gist.github.com/douglasmakey/2c6be5a13a7eda83aae38afc8d151650 


---
title: "Copy or Move?"
id: rust-copy-or-move
tags: ["rust"]
connections: ["rust"]
published_date: "2025-02-20"
description: "Learn about Rust's copy and move semantics."
---

## Who Decides if Something Is Copied or Moved? What Criteria Are Used?
- **Language Semantics**: In `Rust`, the decision whether a type is copied or moved is made by the language’s ownership and type system. This decision is based on whether the type implements the Copy trait.
- **Implementing `Copy`**:
	- **Automatically Implemented**: Some types, like primitive types (e.g., `integers`, `floats`, and `pointers`), automatically implement `Copy`.
	- **Manual Implementation**: For user-defined types, we can implement `Copy` (often together with `Clone`) if the type has a “trivial” bitwise copy semantics. This is usually acceptable when our type doesn’t manage resources (like heap memory, file handles, etc.) that require special cleanup.

- **Move Semantics**: If a type does not implement `Copy`, then assignments and passing the type to functions result in moves. A move transfers ownership from one variable to another and invalidates the original binding (unless the type implements the `Clone` trait and we explicitly clone it).

Thus, the criteria are:
- **Does the type contain data that can be safely duplicated by a bitwise copy?**
- **Does duplicating the type risk duplicating ownership of a resource?**

If the answer is **“yes, it can be safely duplicated,”** then the type should implement `Copy`, and the language will treat operations like dereferencing a raw pointer as creating a copy.


Learn about Rust's copy and move semantics.

---
title: "Rust PartialEq, Eq, PartialOrd and Ord"
id: "rust-equality-and-ordering"
tags: ["rust"]
connections: ["rust"]
published_date: "2025-02-20"
description: "Understanding Rust's Equality and Ordering Traits"
---

## Overview of Equality and Ordering Traits
1. **PartialEq**:
   - Allows the use of `==` and `!=`.
   - Supports "partial" equality for types where some comparisons might be undefined (e.g., floating-point numbers with NaN).
2. **Eq**:
   - A marker trait indicating that equality is total (i.e., every value can be compared to every other value, and the relation is reflexive, symmetric, and transitive).
3. **PartialOrd**:
   - Enables ordering comparisons (`<`, `>`, `<=`, `>=`).
   - Returns an `Option<Ordering>` because not all pairs of values might be comparable.
4. **Ord**:
   - Specifies a total order by implementing the cmp method.
   - Requires that every pair of elements yields a definitive ordering (`Less`, `Equal`, or `Greater`).

## The Price Struct Example

```rust
// Using rust_decimal crate
use rust_decimal::Decimal;
use rust_decimal_macros::dec;

#[derive(Debug, Clone, Copy)]
pub struct Price {
    pub list: Decimal,
    pub offer: Option<Decimal>,
}
```

### What It Represents
- **list**: The regular price.
- **offer**: An optional discounted price.

### Defining the "Effective Price"
For our domain, the effective price is defined as:

1. If an offer exists, use it.
2. Otherwise, use the list price.

This concept is central because:
- It drives how equality and ordering will be determined.
- It allows a "discounted" price logic, meaning a price with an offer (if lower) should be considered "cheaper" than one without.

```rust
impl Price {
    // Other methods...
    
    /// Returns the effective price:
    /// if an offer is provided, it's the offer; otherwise it's the list price.
    fn effective(&self) -> Decimal {
        self.offer.unwrap_or(self.list)
    }
}
```

### Custom Equality and Ordering Implementations

Since our test cases require specific behavior, we will implement custom versions of the traits.

### Equality: PartialEq and Eq

```rust
/// Two prices are equal if they have the same effective price and list price
impl PartialEq for Price {
    fn eq(&self, other: &Self) -> bool {
        self.effective() == other.effective() && self.list == other.list
    }
}

/// Marker trait indicating Price implements total equality
impl Eq for Price {}
```

### Ordering: PartialOrd and Ord

For ordering, the primary key is the effective price. If the effective prices are equal, compare the list prices:

```rust
use std::cmp::Ordering;

/// Total ordering based on effective price first, then list price as a tie-breaker
impl Ord for Price {
    fn cmp(&self, other: &Self) -> Ordering {
        match self.effective().cmp(&other.effective()) {
            Ordering::Equal => self.list.cmp(&other.list),
            ord => ord,
        }
    }
}

/// Partial ordering that delegates to the total ordering implementation
impl PartialOrd for Price {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}
```

### Example Usage

```rust
// Example usage in collections
let mut prices = vec![
   Price {
         list: Decimal::from_f32(10.0).unwrap(),
         offer: Some(Decimal::from_f32(8.0).unwrap()),
   },
   Price {
         list: Decimal::from_f32(5.0).unwrap(),
         offer: None,
   },
];

prices.sort(); // Works because we implemented Ord
let min_price = prices.iter().min().unwrap(); // Gets the lowest price
assert_eq!(min_price, &Price {
   list: Decimal::from_f32(5.0).unwrap(),
   offer: None,
});

// Using prices in a sorted collection
use std::collections::BTreeSet;
let mut price_set = BTreeSet::new();

price_set.insert(Price {
   list: Decimal::from_f32(10.0).unwrap(),
   offer: Some(Decimal::from_f32(8.0).unwrap()),
});

price_set.insert(Price {
   list: Decimal::from_f32(5.0).unwrap(),
   offer: None,
});

assert_eq!(price_set.iter().min().unwrap(), &Price {
   list: Decimal::from_f32(5.0).unwrap(),
   offer: None,
});
```

### Property-Based Testing

It's important to verify that our implementations satisfy the expected properties of these traits:

```rust
#[test]
fn test_reflexivity() {
   let price = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   assert_eq!(price, price);
}

#[test]
fn test_symmetry() {
   let a = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   let b = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   assert_eq!(a == b, b == a);
}

#[test]
fn test_transitivity() {
   let a = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   let b = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   let c = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   
   assert!(a == b && b == c && a == c);
}

#[test]
fn test_ord_consistency() {
   let a = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   let b = Price { list: Decimal::from_f32(10.0).unwrap(), offer: Some(Decimal::from_f32(8.0).unwrap()) };
   
   // If two values compare equal under Ord, they should be equal under PartialEq
   assert!(a.cmp(&b) == Ordering::Equal && a == b);
}
```

## Total vs. Partial Comparisons

### Total Equality and Total Ordering
1. **Total Equality (Eq and PartialEq)**:
   - Implement these when every instance of our type can be compared without any ambiguity. For example, if we know that for any two values, either they are equal or they are not (with no edge cases like "undefined" comparisons), then we should implement both `PartialEq` and `Eq`.
   - **Use Case**: Types that do not include `floating-point` numbers with `NaN`, or any values that might be "incomparable."
   - **Example**: Our Price type, when based on Decimal (assuming it provides total equality), should implement both so that if two prices compare equal in ordering (via `Ord`) they are also equal with `Eq`.

2. **Total Ordering (Ord and PartialOrd)**:
   - Implement these when we can always determine a clear ordering between any two instances of our type. If every pair of elements can be compared to yield a definitive ordering (`Less`, `Equal`, or `Greater`), we should implement both `PartialOrd` and `Ord`.
   - **Use Case**: Types that need to be used in sorted collections (like `BTreeMap` or `BTreeSet`) require a total order.
   - **Example**: In our custom Price example, if we define the ordering based on the effective price (offer if available, otherwise list) and then use the list price as a tie-breaker, every Price value can be compared with any other.

### Partial Equality and Partial Ordering
1. **Partial Equality (PartialEq without Eq)**:
   - Use just `PartialEq` when there might be cases where comparison is not fully defined. A classic example is `floating-point` numbers (e.g., `f32` or `f64`) where `NaN != NaN` makes equality a "partial" concept.
   - **When Not to Use Eq**: If our type can contain values for which equality isn't reflexive or total (e.g., if it embeds floats that might be `NaN`), we should only implement `PartialEq`.

2. **Partial Ordering (PartialOrd without Ord)**:
   - Use `PartialOrd` when not all elements can be compared. Again, `floating-point` numbers are a classic case since comparisons involving `NaN` yield `None` rather than an `Ordering`.
   - **When Not to Use Ord**: If our type can encounter undefined comparisons (or if the notion of ordering isn't complete), implement `PartialOrd` alone.
   - **Example**: If our type had a field that could sometimes be "missing" or "undefined" (beyond the normal Option handling), we might only provide a partial order.

## Trait Relationships and Consistency
- **Consistency Is Key**:
  - If we implement `Ord`, it implies a total order. One of the guarantees we must provide is that if `a.cmp(&b)` returns `Ordering::Equal`, then `a == b` must hold under our `PartialEq` implementation.
  - **Practical Impact**: When designing our custom implementations (as in the Price example), ensure that the fields we use for ordering are the same fields (or logically equivalent values) we use for equality.

- **Implementation Dependencies**:
  - `Ord` requires that we also implement `PartialOrd`.
  - `Eq` requires that we implement `PartialEq`.
  - In most cases, if we can derive `Ord` (because all our inner types are totally ordered), we will also derive `Eq`.

## Common Pitfalls

1. **Inconsistency Between Ord and PartialEq**:
   - If `a.cmp(&b) == Ordering::Equal` but `a != b`, this violates the contract and can lead to unpredictable behavior in collections.

2. **Using Derived Implementations When Custom Logic Is Needed**:
   - The derived implementations compare all fields in order, which may not match our domain requirements (like our "effective price" concept).

3. **Neglecting Edge Cases**:
   - Forgetting to handle special values like empty collections, None options, or boundary values.

4. **Not Testing Contract Properties**:
   - Failing to verify reflexivity, symmetry, and transitivity for equality relations.

## Simplifying with Helper Crates

For simple cases, we might leverage crates that can help with implementations:

```rust
// Using derive_more for simplified implementations
use derive_more::{PartialEq, Eq};

#[derive(PartialEq, Eq)]
struct SimplePrice {
    // Fields
}
```

Other useful crates include:
- `derivative`: Provides more control over derived implementations
- `compare`: Offers utilities for building complex comparisons

## Deciding for Our Own Types
1. **When to Implement Both (Eq + Ord)**:
   - Our type has a clear, total notion of equality and ordering.
   - We want to use our type as a key in sorted collections.
   - Example: A Price type where both the effective price (offer or list) and list price always provide a meaningful, total comparison.

2. **When to Implement Only the Partial Traits (PartialEq + PartialOrd)**:
   - Our type's values might sometimes be "incomparable" (e.g., types containing `floating-point` numbers with `NaN`).
   - We do not need to use our type in contexts where a total order is required (like sorted sets/maps).
   - Example: A custom numeric type that might include invalid or "empty" states where a complete ordering doesn't make sense.

## Takeaways

1. **Consistency Between Traits**:
   - Ensure that if `cmp` returns `Equal`, then the `PartialEq` implementation must also indicate equality. This consistency is crucial when using types in collections that depend on these traits (like sorted sets or maps).

2. **Total vs. Partial Ordering**:
   - If we need to sort our data (for example, in a sorted container like a `BTreeSet`), our type must implement `Ord`. If our type might not have a well-defined order (as with floats), then we may only implement `PartialOrd` or use a wrapper that provides a total order.

3. **Custom vs. Derive**:
   - While deriving traits is convenient, custom implementations let us tailor behavior to fit business logic—such as preferring discounted (offer) prices over list prices.

4. **Testing**:
   - Create tests that express our domain requirements. These tests guide our implementation and ensure that our type behaves correctly in sorting and equality checks.


Understanding Rust's Equality and Ordering Traits

---
title: "Rust Raw Pointers"
id: rust-raw-pointers
tags: ["rust"]
connections: ["rust"]
published_date: "2025-02-20"
description: "Learn about Rust's raw pointers."
---

A **raw pointer** in Rust (such as `*mut T` or `*const T`) is a low-level pointer type similar to those found in `C`. Unlike references in `Rust`, raw pointers:
- Do not have the same safety guarantees.
- Do not carry any lifetime or borrowing information.
- Can be null or dangling.
- Must be dereferenced within an `unsafe` block because the compiler can’t check that they’re valid.

## Representation of raw pointer of T

### The Raw Pointer Itself `ptr`

Consider a raw pointer defined as: 

```rust
let ptr: mut T = /  some pointer value */;
```

- **Memory Address Representation:** The raw pointer `ptr` is essentially just a memory address. For a sized type `T`, `ptr` is stored as a single machine word (e.g., 64 bits on a 64-bit architecture) representing the address in memory where a `T` is (or is supposed to be) located.
    - **Example:** If `ptr` holds the value `0x7ffdf000`, it references the memory at that address.
- **Fat Pointers (for DSTs):** If `T` is an unsized type (for example, a slice `[T]` or a trait object), the pointer is a [fat pointer](https://google.com). This means it contains extra metadata in addition to the memory address. For a slice, the fat pointer includes both:
	- A pointer to the data.
	- The length of the slice.

However, for most simple cases with sized types, we only deal with a single memory address.

### Dereferencing the Raw Pointer `*ptr`

When we dereference the raw pointer with the `*` operator, like so:

```rust
let value: T = unsafe { *ptr };

```
- **What Happens:** Dereferencing accesses the value stored at the memory address contained in `ptr`. The expression `*ptr` yields a value of type `T`.
- **Value Representation:**
	- The value represented by `*ptr` is the sequence of bytes stored at that address, formatted according to the memory layout of `T`.
	- For a simple type like `u32`, `*ptr` might represent 4 bytes that encode an integer (e.g., `0x01 0x00 0x00 0x00` for the number 1 on a little-endian machine).
	- For a struct, `*ptr` would be the contiguous bytes for each field (along with any padding that the compiler introduces according to the struct’s layout).
- **Example:** If we have:

```rust
let x: u32 = 42;
let ptr: *const u32 = &x as *const u32;
```

Here, `ptr` is the memory address where `x` is stored, and dereferencing it returns the value **42** (which might be represented in binary as 4 bytes, e.g., `0x2A 0x00 0x00 0x00` on a little-endian system).

### Summary of Representations

- **ptr (the raw pointer itself):**
	- **Type:** `*mut T` or `*const T`.
	- **Representation:**
		- For sized types, a single machine word holding the memory address.
		- For unsized types (fat pointers), a tuple of the memory address and additional metadata (like length for slices or a vtable pointer for trait objects).
- **\*ptr (dereferencing the pointer):**
	- **Type:** `T`.
	- **Representation:**
		- The actual bytes stored at the memory location pointed to by `ptr`, formatted according to `T`’s memory layout.
		- This is the concrete data that lives at that address (for example, an integer, a struct, etc.).


##  Unsafe for dereferencing

Consider the DDoS example using Aya from my [article](https://www.kungfudev.com/blog/2023/11/21/ddos-mitigation-with-rust-and-aya). In the following snippet, we see a more complex instance of creating and dereferencing raw pointers:

```rust
let ip_hdr: *mut Ipv4Hdr = get_mut_ptr_at(&ctx, EthHdr::LEN)?; // Safe: pointer creation

match unsafe { (*ip_hdr).proto } { // Unsafe: dereferencing
    IpProto::Udp => {}
    _ => return Ok(xdp_action::XDP_PASS),
}
```

- **Creating a Raw Pointer:**
Creating a raw pointer (e.g., `*mut Ipv4Hdr`) is safe because it only involves storing a memory address. At this stage, Rust does not enforce any safety guarantees since no memory is actually accessed.
- **Dereferencing a Raw Pointer:**
Dereferencing a raw pointer (e.g., `*ip_hdr`) is unsafe because it accesses the memory location the pointer refers to. When dereferencing, Rust cannot guarantee:
	- The pointer is non-null.
	- The memory is valid (i.e., it has not been freed or reallocated).
	- The pointer is properly aligned.
	- There are no aliasing violations (such as concurrent mutable access).

## Coercing a Reference to a Raw Pointer

> At runtime, a raw pointer  and a reference pointing to the same piece of data have an identical representation. In fact, an &T reference will implicitly coerce to an  const T raw pointer in safe code and similarly for the mut variants (both coercions can be performed explicitly with, respectively, value as *const T and value as *mut T).
> 
> Ref https://web.mit.edu/rust-lang_v1.25/arch/amd64_ubuntu1404/share/doc/rust/html/book/first-edition/raw-pointers.html 

Coercion from a reference to a raw pointer is straightforward and safe. The conversion itself does not require an unsafe block because references are already guaranteed to be valid (non-null and aligned).

#### From an Immutable Reference ( &T):

**Implicit Coercion:**
When we have a reference, we can directly assign it to a raw pointer of type `*const T`.

```rust
let value = 42;
let ref_value: &i32 = &value;
let raw_value: *const i32 = ref_value; // Implicitly coerced to a raw pointer

```

#### From a Mutable Reference ( &mut T):

**To a Mutable Raw Pointer:**
Similarly, a mutable reference can be coerced into a `*mut T`.

```rust
let mut mutable_value = 100;
let ref_mut_value: &mut i32 = &mut mutable_value;
let raw_mut_value: *mut i32 = ref_mut_value; // Implicit coercion

```

**To an Immutable Raw Pointer:**
A mutable reference can also be coerced into a `*const T` (by first being viewed as an immutable reference).

```rust
let raw_const_value: *const i32 = ref_mut_value; // Coerced as &mut i32 -> &i32 -> *const i32
```

**Important Note:**
we cannot coerce an immutable reference ( `&T`) into a mutable raw pointer ( `*mut T`) because that would break Rust's guarantees about mutability and aliasing.

## Moving Out of a Value Behind a Raw Pointer

Consider the following code:

```rust
struct NotCopy(String);
let x = NotCopy(String::from("Hello"));
let ptr: *const NotCopy = &x;
// Error
let y: NotCopy = unsafe { *ptr }; // cannot move out of `*ptr` which is behind a raw pointer

```

### Understanding the Error

1. **Non-Copy Type:**
	- The struct `NotCopy` does not implement the `Copy` trait because it contains a `String`, and `String` is not `Copy`.
	- In `Rust`, moving a value (as opposed to copying it) transfers ownership, and after a move the original value cannot be used.
2. **Dereferencing a Raw Pointer:**
	- When we write `*ptr`, we are dereferencing the raw pointer. For types that are not `Copy`, this operation attempts to move the value out of the memory location.
	- Even though the operation is in an `unsafe` block (which means we’re telling the compiler “I know what I’m doing”), `Rust` still enforces its move semantics at compile time.
3. **Moving from Behind a Pointer:**
	- The compiler error is essentially saying: *"we cannot move the value out of *ptr because that value is not Copy and it lives somewhere that is borrowed (via the pointer)."**
	- In safe `Rust`, we cannot move out of a reference (or a raw pointer in this case) because that would leave the original location in an invalid state while it’s still accessible by its original owner ( `x` in our example).

### What’s Really Happening

- **Ownership & Move Semantics:**
	- The value `x` owns its data. When we attempt to execute `unsafe *ptr`, we try to transfer that ownership (i.e., move the value) from `x` via a raw pointer. `Rust` prevents this because `x` would still be valid after the move attempt, leading to two owners or leaving `x` in an undefined state, which violates `Rust` safety guarantees.
- **Raw Pointers and Safety:**
	- Raw pointers ( `const T` or `mut T`) allow us to bypass some of Rust's safety checks, but they do not bypass ownership and move rules. The compiler ensures that dereferencing a pointer to a non- `Copy` type does not inadvertently move the value without proper precautions.

### Use std::ptr::read to Move the Value

If we truly want to move the value out of the pointer (transferring ownership from `x` to `y`), we can use `std::ptr::read`:

```rust
use std::ptr;

let x = NotCopy(String::from("Hello"));
let ptr: *const NotCopy = &x;

// Move the value out of the pointer.
let y: NotCopy = unsafe { ptr::read(ptr) };

// Prevent `x` from being dropped, since its value has been moved.
std::mem::forget(x);
```

**Important Notes:**
- After using `ptr::read`, the memory where `x` resided still exists but now holds a “moved-from” value.
- Accessing `x` after this operation is undefined behavior.
- Calling `std::mem::forget(x)` ensures that `x`'s destructor is not run, preventing a potential double-drop.

So the main error error occurs because we are trying to move (transfer ownership of) a `non-Copy` value ( `NotCopy`) out of a raw pointer. Moving out of a value behind a pointer (or reference) is disallowed because it would leave the original owner (`x`) in an invalid state.


Ny Notes

Notes View all