Initial commit

Author: george-lim

.github/workflows/cd.yaml

@@ -0,0 +1,16 @@
+name: CD
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+      - uses: chetan/git-restore-mtime-action@v2
+      - run: cargo publish --token ${CRATES_IO_API_TOKEN}
+        env:
+          CRATES_IO_API_TOKEN: ${{ secrets.CRATES_IO_API_TOKEN }}

.github/workflows/ci.yaml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    name: Run checks and tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt, clippy
+      - uses: chetan/git-restore-mtime-action@v2
+      - uses: actions-rust-lang/rustfmt@v1
+      - uses: giraffate/clippy-action@v1
+        with:
+          reporter: github-check
+      - run: cargo test

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.lock

@@ -0,0 +1,16 @@
+[package]
+name = "ordered-pool-allocator"
+version = "0.1.0"
+authors = ["George Lim <lim.george@me.com>"]
+edition = "2021"
+description = "A fast and compact pool allocator with block sorting support."
+repository = "https://github.com/george-lim/ordered-pool-allocator"
+license = "MIT OR Apache-2.0"
+keywords = ["allocator", "memory-pool"]
+categories = ["data-structures", "memory-management"]
+
+[dev-dependencies]
+rand = "0.8"
+
+[profile.test]
+opt-level = 3

Cargo.toml

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 George Lim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -0,0 +1,29 @@
+# Ordered Pool Allocator
+
+[![crates.io](https://img.shields.io/crates/v/ordered-pool-allocator)](https://crates.io/crates/ordered-pool-allocator)
+[![ci](https://github.com/george-lim/ordered-pool-allocator/workflows/CI/badge.svg)](https://github.com/george-lim/ordered-pool-allocator/actions)
+[![license](https://img.shields.io/github/license/george-lim/ordered-pool-allocator)](https://github.com/george-lim/ordered-pool-allocator/blob/main/LICENSE)
+
+A fast and compact pool allocator with O(1) block access, allocation, and deallocation; as well as O(nlog(n)) block sorting.
+
+This project is a learning exercise to explore how memory pools work and how to optimize for small header size and for specific operations, like sorting memory blocks.
+
+## Design
+
+### Physical vs virtual block indices
+
+To ensure that existing allocated block pointers still point to their respective blocks after sorting, we need to sort block indices instead of the blocks themselves. This means we need to define two types of indices: physical and virtual.
+
+Physical block indices are used to locate the physical block in memory and are fixed. Virtual block indices represent the current virtual order of the blocks in the allocator. These indices should not be stored, as they can point to different physical blocks after sorting or block deallocation. Assuming blocks are never deallocated or sorted, the virtual and physical block indices are guaranteed to be in sync.
+
+### Header
+
+In order to achieve the fastest time complexity for block allocation and deallocation, we need to store three things in addition to the physical blocks:
+
+1. A map of currently allocated virtual block indices to physical block indices (`physical_block_indices`). This allows the allocator to find the correct physical block while performing block indexing.
+2. A map of currently allocated physical block indices to virtual block indices (`virtual_block_indices`). This allows the allocator to find the virtual block index to update in O(1) time for the given block pointer during block deallocation.
+3. A stack of physical block indices that were previously deallocated. This allows the allocator to find existing deallocated blocks in O(1) time during block allocation.
+
+### Memory Layout
+
+![memory-layout](https://github.com/george-lim/ordered-pool-allocator/assets/21700768/24c78c1d-e0d4-48ce-9d0d-963fb45dde9b)