Proper Types

When we talk about types, we often mean something like this:

struct MyData {
	name: String,
	val: i32
}

This is a simple collection of data. The properties of this type are completely static— name will always be a String and val will always be an i32. We call these proper types. They are in a fixed and usable state; in other words, we know everything we can know about them.

Types.. kinda

Lets generalize this type to hold any value we could want:

struct MyData<T> {
	name: String,
	val: T
}

Now this type can composed of any other type, and the “type” T is actually just a placeholder for what we could later place inside this.

So.. this clearly doesn't fit the definition of a proper type that we previously defined, so what is it? Lets try analyzing what the compiler does with this type under the hood. Lets take the following code:

let data_a = MyData::new("asdf".into(), 12);
let data_b = MyData::new("asdf".into(), true);

And try searching for a MyData symbol:

nm target/debug/higher_orders_types | grep MyData

And we should see some output like this:

_ZN4core3ptr59drop_in_place$LT$higher_orders_types..MyData$LT$i32$GT$$GT$17h08f26c464aa8b7e0E
_ZN4core3ptr60drop_in_place$LT$higher_orders_types..MyData$LT$bool$GT$$GT$17hf107324ff7a39b31E

Bingo!

These lines say MyData$LT$i32 and MyData$LT$bool, so we can see that rust will actually generate concrete types for whatever gets used inside the generic! [^1]

Lets generalize this idea back into a type theory context: we can say that MyData is a special kind of type, that takes a proper type, and returns a proper type.

Improper Types

Just with higher-order-functions, we can see that this type is a level above concrete types. These are called kinds. A kind is a type constructor that takes a type, and produces a new type.

So now that we have a new concept to play with, what can we do with it? Well, lets see what Haskell does with it:

class Functor f where
    fmap :: (a -> b) -> f a -> f b

If you don't know any haskell, this likely looks very arcane to you. Lets write it in the style of rust:

trait Functor {
	fn fmap<A, B>(
		f: impl Fn(A) -> B, 
		Self<A>
	) -> Self<B>;
}

So fmap takes a function of A -> B and a Self<A>, maps said function on the inner value, and returns a Self<B>. If you try to compile this, you'll get an error akin to “Self takes 0 parameters.” Rust doesn't have a notion of kinds, only parametric polymorphism, so we cant refer to a kind as something on its own. So making this trait will be a little messier, but we can still do it:

trait Functor<A, B>: Sized {
    //type Ma; will be Self
    type Mb;
    
    fn fmap(f: impl Fn(A) -> B, rhs: Self) -> Self::Mb;
}

We can't guarantee that Mb will be Self<B>[^2], but we can at least now use this trait on Option.

impl<A, B> Functor<A, B> for Option<A> {
    type Mb = Option<B>;

    fn fmap(f: impl Fn(A) -> B, rhs: Self) -> Self::Mb {
        match rhs {
            Some(v) => Some(f(v)),
            None => None,
        }
    }
}

Actually, while we're rusti-fying this, lets turn it into a method.

fn fmap(self, f: impl Fn(A) -> B) -> Self::Mb {
    match self {
        Some(v) => Some(f(v)),
        None => None,
    }
}

You've most definitely realized at this point that this is identical to a method that already exists, map. If you squint a little, you'll even notice that lots of rust methods come from haskell typeclasses!

Since haskell supports kinds[^3], its able to soundly model these sorts of actions. Its so capable that haskell actually uses a monad to introduce side effects into a purely functional language! Its monads all the way down.

Footnotes

1. in this case you can see that rust is actually generating the drop_in_place function, so that it can call any destructors when these variables go out of scope
2. there are actually a lot of ways you could go about solving this, decided to go with a relatively naive/straightforward path
3. its probably more correct to say “haskell supports curried type constructors”
4. i lightly refered to a type theory page (mostly just to make sure i was using the right words) on wikipedia when i was writing this, check that out for more fp mumbo-jumbo!

maybe sometime ill write more about monads for real, but thats a whole thing that i didnt want to get into. the point of this article was to bridge the gap and expose some of rusts fp roots, and why i think its so cool. thnx for reading! <3

Structure

Heres our base:

pub struct Vec<T> {
    ptr: NonNull<T>,
    len: usize,
    cap: usize,
}

impl<T> Vec<T> {
    const LAYOUT: Layout = Layout::new::<T>();
    const GLOBAL: Global = Global;
    
    pub fn new() -> Self {
        Self { ptr: NonNull::dangling(), len: 0, cap: 0 }
    }
}

A couple things are structured a little differently than before.

1. we have addictional len and cap fields
2. a Layout is generated as an associated constant for any given type
3. We get a “hook” to global so that we dont need to call default() every time

This way we don't need to call Global::default() or Layout::new::<T>() every time we want to use them. For new, we get a “dangling” pointer, or one that doesn't point to allocated memory, just so we have something to put in our struct. This is okay, because no elements will be read if cap, and by extention len, is 0.

Push

The first real code we'll write is for adding an element to the end of the block. Lets map out what should happen.

pub fn push(&mut self, x: T) {
	if self.len == self.cap {
		//allocate more memory
		//increase self.cap
	}

	//increase self.len
	//write x into self[self.len-1]
}

First, lets handle reallocating our vector when it needs to grow. I'll be using the alloc_layout_extra feature for better layout syntax, but this isnt necessary. The Allocator trait has a method called grow, which takes a pointer, its layout, and the new layout to fit.

// repeat() will error on overflow
// also returns a tuple with other data
// that we dont need
let curr_lay = Self::LAYOUT.repeat(self.cap).unwrap().0;
let new_lay = Self::LAYOUT.repeat(self.cap+1).unwrap().0;

let new_ptr = unsafe {
	Self::GLOBAL.grow(
		self.ptr.cast(),
		curr_lay,
		new_lay,
	)
};

The repeat() method creates a new layout based on size_of::<T>() * n, so we use it to create layouts representative of our current and desired allocations.

new_ptr is currently a result whos error type is equivalent to the pointer just being null, so lets unwrap it and update our data.

self.ptr = new_ptr.unwrap().cast();
self.cap += 1;

Actually, lets extract this procedure into a more generic function:

fn realloc(&mut self, size: usize) {
	let curr_lay = Self::LAYOUT.repeat(self.cap).unwrap().0;
	let new_lay = Self::LAYOUT.repeat(self.cap+size).unwrap().0;
	
	let new_ptr = unsafe { Self::GLOBAL.grow(
		self.ptr.cast(),
		curr_lay,
		new_lay,
	)};
	
	self.ptr = new_ptr.unwrap().cast();
	self.cap += size;	
}

Thats the hard part, so lets go back to our push function. Now the rest of the function is pretty self-explanatory:

pub fn push(&mut self, x: T) {
	if self.len == self.cap {
		self.realloc(1);
	}

	//increase self.len
	//write x into self[self.len-1]
	self.len += 1;
	unsafe { self.ptr.add(self.len-1).write(x) };
}

Pop

Next lets make a function to remove the last element in the vector.

pub fn pop(&mut self) -> Option<T> {
	if self.len == 0 { return None }
	self.len -= 1;
}

Now we need to get the last element. We want to preserve move semantics, but this isn't safely possible with raw pointers.

A Note on Memory Safety

When we read the data from the pointer, we effectively make a bitwise copy of that data. As is discussed in the Copy trait docs, doing this when you shouldn't can lead to some very serious problems. We need to guarantee that only 1 instance of that data can ever be accessed safely [^1].

So, if we want to move data from the heap to the stack, we need to make sure that the heap copy is dead in the water. For that rule to be violated, self.len needs to be increased without writing data to the expanded memory. We aren't responsible for memory past self.len, and it could be literally anything. Therefore, we need to make sure self.len can only be changed when we take special precautions [^2]. Luckily our push and pop methods will do exactly that.

So with that out of the way, lets write our 3 lines of code that necessitated that divergence:

let last = unsafe { self.ptr.add(self.len) };
self.len -= 1;

//moves out of pointer
Some(unsafe { last.read() })

Theres our core functionality of a vector! Lets write a couple index functions:

pub fn get(&self, idx: usize) -> Option<&T> {
    if self.len == 0 { return None }

    Some(unsafe { self.ptr.add(idx).as_ref() })
}
pub fn get_mut(&mut self, idx: usize) -> Option<&mut T> {
    if self.len == 0 { return None }
    Some(unsafe { self.ptr.add(idx).as_mut() })
}

And quickly implement drop:

impl<T> Drop for Vec<T> {
    fn drop(&mut self) {
        for i in 0..self.len {
		//call all destructors
        	unsafe { self.ptr.add(i).drop_in_place() };
        }
    }
}

And we've recreated the most important functions of Vec!

1. we dont need to make it completely impossible, we just need to make sure that safe rust can't
2. it wouldnt be a bad idea to consider changing self.len unsafe, in fact std's Vec does this

thanks for reading part 2! This was super fun to write, and i might make a part 3 to implement a bunch of common traits on our vec, lmk if you think that would be cool!

Step 0: Learn the Allocator

Rust's allocator API is hidden behind the aptly named feature:

#![feature(allocator_api)]
#![feature(non_null_convenience)] //more methods for a type later on

This gives us a lot of things, but for this we just need to worry about Global, Layout, and the Allocator trait:

use std::alloc::{Layout, Global, Allocator};

Lets get started and re-invent Box: a type that allocates a single item. All it is is a pointer!

pub struct Box<T>(*mut T);

impl<T> Box<T> {
    pub fn new(item: T) -> Self {
        todo!()
    }
}

The thing we interface with is Global. Because of the way it works, there isn't a single static to refer to, we need to just use default() to get a handle to it [^1]. Lets take a look at the allocator trait. Immediately, we find the most important function:

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

This takes something called a Layout, and returns something called NonNull. Lets cover these.

The Layout Type

Theres actually a lot more info about a pointer than just the exact address it points to. We also need to know how big the item is, so that we know how many bytes to read. Usually this is static and provided by the type, but with dynamically sized types like [T] it needs to be carried around with the pointer itself (something called a “wide-pointer”). On top of that, pointers have something called an alignment, which requires that they begin on an address divisible by a power of two[^2]. Layout carries all of this info for us, and actually provides a method to generate it from a type:

let layout = Layout::new::<T>();

The NonNull Type

Pointers shouldn't be null. Rust provides functional error handling schemes like Option that are very preferred over sentinel values for a multitude of reasons. This leads to the situation where OxO is a representable value, but should never be constructed. NonNull enforces this invariant: it asserts that it will never be null. The main caveat of Option is that we need to carry along another entire boolean byte just to keep track of which variant it is. However, with NonNull we now have a forbidden value that the compiler promises will never exist! As such, NonNull provides whats called niche optimization: Option will use the forbidden 0x0 value as the discriminant of None, and means that it doesn't need any more size than the type itself. Cool stuff!

assert_eq!(size_of::<NonNull<u8>>(), size_of::<Option<NonNull<u8>>>());

Lets change the pointer type in our box, as it'll always be valid.

pub struct Box<T>(NonNull<T>);

Getting Memory

Back to the function! Lets get the allocator and give it a layout of our type:

let layout = Layout::new::<T>();
let ptr = Global::default().allocate(layout).unwrap();
let ptr = ptr.cast::<T>();

Now we have a pointer to some of our own data on the heap! First thing you'll notice is that we actually need to manually cast the pointer to the type we need, as allocate simply returns a slice of bytes. Lets not forget to actually write our data into that allocation:

unsafe { ptr.write(item) };

This is unsafe as we need to guarantee that we are allowed to write to that space in memory. Since we just allocated that memory with a layout generated from T, we know that this is okay.

Getting rid of the Memory

We have a situation now where the default drop actually doesn't suffice. All rust does right now is delete the pointer when the box gets dropped. But the allocator doesn't know that happened! This is called a memory leak, where data has been allocated on the heap, and all pointers to that memory are destroyed without reallocating. Our data is doomed to forever sit untouched on the heap, alone and forgotten. Luckily, rust has destructors. Implementing the Drop trait lets us run arbitrary code before the data gets destroyed, so this is the perfect place to deallocate!

impl<T> Drop for Box<T> {
    fn drop(&mut self) {
        unsafe { self.0.drop_in_place() };

        unsafe { 
            Global::default().deallocate(
                self.0.cast(), Layout::new::<T>()
            ) 
        };
    }
}

This is pretty similar to when we created the box, just in reverse. Once again, we need to provide a NonNull<u8>, which is why we call cast(), and the layout of our type. We also want to make sure that whatever deconstructor T has is run, with drop_in_place. This method is unsafe because it doesn't actually remvove the data in that memory, it simply runs the Drop implementation. Reading that memory from that point forward is undefined behavior.

And thats all she wrote! Along with a simple Deref impl, we've created a safe abstraction for storing data on the heap!

impl<T> Box<T> {
    pub fn new(item: T) -> Self {
        let layout = Layout::new::<T>();
        let ptr = Global::default().allocate(layout).unwrap();
        let ptr = ptr.cast::<T>();
        unsafe { ptr.write(item) };

        Self(ptr)
    }
}

impl<T> Drop for Box<T> {
    fn drop(&mut self) {
        unsafe { self.0.drop_in_place() };
        unsafe { 
            Global::default().deallocate(
                self.0.cast(), Layout::new::<T>()
            ) 
        };
    }
}

impl<T> Deref for Box<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        //we know that this is safe because we can only get a Box from a safe function
        unsafe { self.0.as_ref() }
    }
}

1. Alternatively, you could store the allocator in the struct, as it takes up no size.
2. Alignment is admittedly something I barely understand, I simply take it as a weird optimization that hardware does, and it really doesn't like when you break it.

thank you for reading <3 i plan to write a part 2 soon that implements vec. i figured it would be better to teach the allocator api in its own smaller article. sorry to those who read this before i added the deallocation part. oops...