Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/shadyfennec/stupidalloc

A stupid Rust memory allocator
https://github.com/shadyfennec/stupidalloc

memory-management rust

Last synced: about 2 months ago
JSON representation

A stupid Rust memory allocator

Awesome Lists containing this project

README 

        
# Stupid alloc - what if memory allocation was annoying

Mostly a weird exercise in how much you can make a memory allocator suck.



This allocator will create and open files to use as the allocation's data, through a memory map. If you enable the `interactive` feature, it will even prompt you for a file name every time

the program allocates something! Cool!



## How to use it

don't



## No but really how does one use this

Using `cargo add`:



```shell

cargo add stupidalloc

```



Manually specifying the dependency in `Cargo.toml`:



```toml

[dependencies]

stupidalloc = { version = "0.2.1" }

```



### The `interactive` feature

The crate comes with a feature, `interactive`, that will open confirmation and file picker dialog windows instead of silently opening and allocating memory. Enable it at your own risk,

as sometimes dialogs are unavailable. This crate uses [`native-dialog`](https://crates.io/crates/native-dialog) for this feature.



### Graphical interface

The `graphics` feature creates graphical windows that display memory contents as black or white pixels, representing the bits of the allocations! Click on each pixel to either set the bit (left click) or clear the bit (right click). You can easily modify memory contents this way!



Additionally, the `always-graphics` feature enables graphical windows for every single new allocation performed, and not just creation on-demand by the user.



Graphical windows are created using the [`minifb`](https://crates.io/crates/minifb) crate.



https://github.com/shadyfennec/stupidalloc/assets/68575248/b19790c7-bc9e-4a59-99c9-18d7e308739e



### Logging

The `logging` crate creates companion logging files that record useful information about each allocation, using the familiar Markdown format. Useful for debugging!



## Using the allocator

- You can use it as the global allocator of your program, but it may lead to wonkiness and weird stuff like prompting for allocations before `main()` is executed!



```rust

use stupidalloc::StupidAlloc;



#[global_allocator]

static GLOBAL: StupidAlloc = StupidAlloc;



fn main() {

    // ...

}

```



- By using the [`allocator_api`](https://doc.rust-lang.org/beta/unstable-book/library-features/allocator-api.html) nightly feature, you can selectively

allocate single objects with this allocator:



```rust

// Requires nightly

#![feature(allocator_api)]



use stupidalloc::StupidAlloc;



fn main() {

    let normal_box = Box::new(1);



    let stupid_box = Box::new_in(1, StupidAlloc);

}

```



A cool usage is to stop the execution of your program (through your favourite `stdin` read) and then go look at the allocation files with a hex editor (might I recommend [Hexyl](https://github.com/sharkdp/hexyl)?)



To help you with that, the allocator exposes a few helper functions:

- `StupidAlloc.state()` returns a `HashMap` where the key is the address of the memory map (and so the address of the allocated object), and the value is a `PathBuf` to the associated file.

- `StupidAlloc` implements `fmt::Display`, so running `println!("{StupidAlloc}")` will print a lovely summary of all the allocations currently being tracked.

- `StupidAlloc.file_of(x)` will return the file associated to the linked object, if it exists. Obviously this only works with stuff allocated with the stupid allocator. An example of use:



```rust

// Still requires nightly

#![feature(allocator_api)]



use stupidalloc::StupidAlloc;



fn main() {

    let stupid_box = Box::new_in(1, StupidAlloc);



    // Since it's a Box, we need to pass &i32 to the function to get the 

    // address of where the integer is.

    let file = StupidAlloc.file_of(&*stupid_box).unwrap();



    // Go nuts with it!

}

```



Another cool usage is to be able to see how stuff is laid out in memory, without

having to use memory viewers or complicated GDB syntax!



For example, ever wanted to see how a `Vec` is organised in memory?



```rust

use stupidalloc::StupidAlloc;



#[global_allocator]

static GLOBAL: StupidAlloc = StupidAlloc;



fn main() {

    let boxed_vec = Box::new(vec![1, 2, 3]);



    println!("{}", StupidAlloc.file_of(&*boxed_vec).unwrap().display());



    // Somehow pause execution

}

```



This program will print the path of the allocation file for the `Vec` struct

(and not the allocation for the data of the `Vec`, because then we'd only see

the numbers 1, 2, 3!). Open it in a hex viewer, and you can try and guess what

each field is, and try to corroborate it with the [struct's definition](https://doc.rust-lang.org/stable/std/vec/struct.Vec.html).

If your system allows you to (I know Windows can be a bit restrictive), try and 

modify the length and/or capacity fields and see what happens afterwards!



## Disclaimers

- I do not claim that this library is perfect and free of any fault. Here there be typos and mistakes and examples that I didn't test and don't work. Send an issue if something's wrong!

- If you don't have file picker / file dialog capabilities (minimal i3 installation, TTY-only, ...), `interactivity` won't work. 

- Similarly, if you don't have a graphical environment altogether, `graphics` and `always-graphics` won't work either.

- I only tested this on Windows and Linux. If it doesn't work on MacOS or any other OS, sorry. If it doesn't work for you on Windows or Linux: weird! Hit me up.

- If you mess with the memory files in any way you'll mess up with your program memory, but seeing as this is topologically the same as messing with `/proc/mem` I consider this a cool feature.

- I'm probably going to work on this *a little bit more* to add some quality-of-life features, but that's it. It's a shitpost, not a serious library.



## (old) Demo

https://github.com/shadyfennec/stupidalloc/assets/68575248/f2490dc1-8412-4450-9359-7387f79682ea