buddy_alloc.c 1.2025.9

package/CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.10)
+project(buddy_alloc)
+set(C_STANDARD C99)
+
+# Compile C tests
+project(buddy_tests)
+set(C_STANDARD C99)
+set(SOURCE_FILES tests.c)
+add_executable(buddy_tests ${SOURCE_FILES})
+
+# Compile CPP translation unit
+project(buddy_cpp_translation_unit)
+set(CXX_STANDARD C++11)
+set(SOURCE_FILES testcxx.cpp)
+add_executable(buddy_cpp_translation_unit ${SOURCE_FILES})
+
+# Compile benchmark
+project(buddy_bench)
+set(C_STANDARD C99)
+set(SOURCE_FILES bench.c)
+add_executable(buddy_bench ${SOURCE_FILES})

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+https://github.com/spaskalev/buddy_alloc/discussions.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+Thank you for your interest in this project! Feel free to file issues, send pull requests and participate in the discussions.
+
+Pull requests should match the coding style where applicable and preserve the test coverage and resiliency characteristics.

package/LICENSE.md

@@ -0,0 +1,5 @@
+Copyright (C) 2021 by Stanislav Paskalev <spaskalev@protonmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/Makefile

@@ -0,0 +1,59 @@
+#
+# Copyright 2021 Stanislav Paskalev <spaskalev@protonmail.com>
+#
+
+# Disable default implicit rules
+MAKEFLAGS += --no-builtin-rules
+.SUFFIXES:
+
+LLVM_VERSION?=11
+CC?=clang-$(LLVM_VERSION)
+CXX?=clang++-$(LLVM_VERSION)
+CFLAGS?=-std=c99 --coverage -pg -no-pie -fno-builtin -g -O0 -Og -fstrict-aliasing -fstack-protector-all -fsanitize=undefined -fsanitize=bounds -pedantic -Wall -Wextra -Werror -Wfatal-errors -Wformat=2 -Wformat-security -Wconversion -Wcast-qual -Wnull-dereference -Wstack-protector -Warray-bounds -Warray-bounds-pointer-arithmetic -Wassign-enum -Wbad-function-cast -Wconditional-uninitialized -Wfloat-equal -Wformat-type-confusion -Widiomatic-parentheses -Wimplicit-fallthrough -Wloop-analysis -Wpointer-arith -Wshift-sign-overflow -Wshorten-64-to-32 -Wswitch-enum -Wtautological-constant-in-range-compare -Wunreachable-code-aggressive -Wthread-safety -Wthread-safety-beta -Wcomma -Wdeclaration-after-statement -D_FORTIFY_SOURCE=3
+CXXFLAGS?=-std=c++11 --coverage -pg -no-pie -fno-builtin -g -O0 -Og -fstrict-aliasing -fstack-protector-all -fsanitize=undefined -fsanitize=bounds -pedantic -Wall -Wextra -Wformat=2 -Wformat-security -Wconversion -Wcast-qual -Wnull-dereference -Wstack-protector -Warray-bounds -Warray-bounds-pointer-arithmetic -Wassign-enum -Wbad-function-cast -Wconditional-uninitialized -Wfloat-equal -Wformat-type-confusion -Widiomatic-parentheses -Wimplicit-fallthrough -Wloop-analysis -Wpointer-arith -Wshift-sign-overflow -Wshorten-64-to-32 -Wswitch-enum -Wtautological-constant-in-range-compare -Wunreachable-code-aggressive -Wthread-safety -Wthread-safety-beta -Wcomma -Wdeclaration-after-statement -D_FORTIFY_SOURCE=3
+LLVM_COV?=llvm-cov-$(LLVM_VERSION)
+CPPCHECK?=cppcheck
+
+TESTS_SRC=tests.c
+TESTCXX_SRC=testcxx.cpp
+LIB_SRC=buddy_alloc.h
+BENCH_SRC=bench.c
+BENCH_CFLAGS?=-O2
+
+test: tests.out
+	rm -f *.gcda
+	./tests.out
+	$(LLVM_COV) gcov -b $(TESTS_SRC) | paste -s -d ',' | sed -e 's/,,/,\n/' | cut -d ',' -f 1,2,3
+	! grep  '#####:' $(LIB_SRC).gcov
+	! grep -E '^branch\s*[0-9]? never executed$$' $(LIB_SRC).gcov
+
+tests.out: $(TESTS_SRC) $(LIB_SRC) test-cppcheck check-recursion
+	$(CC) $(CFLAGS) $(TESTS_SRC) -o $@
+
+test-cppcheck: $(TESTS_SRC)
+	$(CPPCHECK) --error-exitcode=1 --inline-suppr --quiet $^
+
+test-cpp-translation-unit: $(TESTCXX_SRC)
+	$(CXX) $(CXXFLAGS) $(TESTCXX_SRC) -o $@
+
+test-multiplatform: $(TESTS_SRC)
+	# 64-bit
+	powerpc64-linux-gnu-gcc -static $(TESTS_SRC) && ./a.out
+	aarch64-linux-gnu-gcc -static $(TESTS_SRC) && ./a.out
+	# 32-bit
+	i686-linux-gnu-gcc -static -g tests.c && ./a.out
+	powerpc-linux-gnu-gcc -static $(TESTS_SRC) && ./a.out
+
+bench: $(BENCH_SRC) $(LIB_SRC)
+	$(CC) $(BENCH_CFLAGS) $(BENCH_SRC) -o $@
+	./$@
+
+check-recursion: $(LIB_SRC)
+	[ $$( cflow --no-main $(LIB_SRC) | grep -c 'recursive:' ) -eq "0" ]
+
+clean:
+	rm -f a.out *.gcda *.gcno *.gcov tests.out bench
+
+.PHONY: test clean test-cppcheck
+
+.PRECIOUS: tests.out testcxx.out

package/README.md

@@ -0,0 +1,205 @@
+# buddy_alloc
+A buddy memory allocator for C, by [Stanislav Paskalev](https://github.com/spaskalev).
+
+# Status
+
+- [![cicd](https://github.com/spaskalev/buddy_alloc/actions/workflows/main.yml/badge.svg)](https://github.com/spaskalev/buddy_alloc/actions/workflows/main.yml) [![CodeQL](https://github.com/spaskalev/buddy_alloc/actions/workflows/codeql.yml/badge.svg)](https://github.com/spaskalev/buddy_alloc/actions/workflows/codeql.yml)
+- [Latest release](https://github.com/spaskalev/buddy_alloc/releases/latest)
+
+## Licensing
+
+This project is licensed under the 0BSD license. See the LICENSE.md file for details.
+
+## Overview
+
+This is a memory allocator suitable for use in applications that require predictable allocation and deallocation behavior. The allocator's metadata is kept separate from the arena and its size is a function of the arena and minimum allocations sizes.
+
+## Features
+
+- Bounded allocation and deallocation cost
+- Fixed call stack usage, no recursion, no global state
+- C99-compatibility for code and tests
+- 100% line and branch test coverage
+- Supports 32-bit and 64-bit platforms
+- Endian-agnostic, works on both LE and BE
+- Compiles with GCC, Clang, MSVC and Pelles C
+
+## Installation
+
+Run:
+```bash
+$ npm i buddy_alloc.c
+```
+
+And then include `buddy_alloc.h` as follows:
+```c
+#include "node_modules/buddy_alloc.c/buddy_alloc.h"
+```
+
+## Usage
+
+Initializing and using the buddy allocator with metadata external to the arena is done using the `buddy_init` function.
+
+```c
+size_t arena_size = 65536;
+/* You need space for the metadata and for the arena */
+void *buddy_metadata = malloc(buddy_sizeof(arena_size));
+void *buddy_arena = malloc(arena_size);
+struct buddy *buddy = buddy_init(buddy_metadata, buddy_arena, arena_size);
+
+/* Allocate using the buddy allocator */
+void *data = buddy_malloc(buddy, 2048);
+/* Free using the buddy allocator */
+buddy_free(buddy, data);
+
+free(buddy_metadata);
+free(buddy_arena);
+```
+
+Initializing and using the buddy allocator with metadata internal to the arena is done using the `buddy_embed` function.
+
+```c
+size_t arena_size = 65536;
+/* You need space for arena and builtin metadata */
+void *buddy_arena = malloc(arena_size);
+struct buddy *buddy = buddy_embed(buddy_arena, arena_size);
+
+/* Allocate using the buddy allocator */
+void *data = buddy_malloc(buddy, 2048);
+/* Free using the buddy allocator */
+buddy_free(buddy, data);
+
+free(buddy_arena);
+```
+
+## Metadata sizing
+
+The following table documents the allocator metadata space requirements according to desired arena (8MB to 1024GB) and alignment/minimum allocation (64B to 8KB) sizes. The resulting values are rounded up to the nearest unit.
+
+```
+         |     64B |   128B |   256B |   512B |    1KB |    2KB |    4KB |    8KB |
+---------+---------+--------+--------+--------+--------+--------+--------+--------+
+    8 MB |    65KB |   33KB |   17KB |    9KB |    5KB |    3KB |    2KB |   678B |
+   16 MB |   129KB |   65KB |   33KB |   17KB |    9KB |    5KB |    3KB |    2KB |
+   32 MB |   257KB |  129KB |   65KB |   33KB |   17KB |    9KB |    5KB |    3KB |
+   64 MB |   513KB |  257KB |  129KB |   65KB |   33KB |   17KB |    9KB |    5KB |
+  128 MB |     2MB |  513KB |  257KB |  129KB |   65KB |   33KB |   17KB |    9KB |
+  256 MB |     3MB |    2MB |  513KB |  257KB |  129KB |   65KB |   33KB |   17KB |
+  512 MB |     5MB |    3MB |    2MB |  513KB |  257KB |  129KB |   65KB |   33KB |
+    1 GB |     9MB |    5MB |    3MB |    2MB |  513KB |  257KB |  129KB |   65KB |
+    2 GB |    17MB |    9MB |    5MB |    3MB |    2MB |  513KB |  257KB |  129KB |
+    4 GB |    33MB |   17MB |    9MB |    5MB |    3MB |    2MB |  513KB |  257KB |
+    8 GB |    65MB |   33MB |   17MB |    9MB |    5MB |    3MB |    2MB |  513KB |
+   16 GB |   129MB |   65MB |   33MB |   17MB |    9MB |    5MB |    3MB |    2MB |
+   32 GB |   257MB |  129MB |   65MB |   33MB |   17MB |    9MB |    5MB |    3MB |
+   64 GB |   513MB |  257MB |  129MB |   65MB |   33MB |   17MB |    9MB |    5MB |
+  128 GB |  1025MB |  513MB |  257MB |  129MB |   65MB |   33MB |   17MB |    9MB |
+  256 GB |  2049MB | 1025MB |  513MB |  257MB |  129MB |   65MB |   33MB |   17MB |
+  512 GB |  4097MB | 2049MB | 1025MB |  513MB |  257MB |  129MB |   65MB |   33MB |
+ 1024 GB |  8193MB | 4097MB | 2049MB | 1025MB |  513MB |  257MB |  129MB |   65MB |
+```
+
+## Design
+
+The allocator was designed with the following requirements in mind.
+
+- Allocation and deallocation operations should behave in a similar and predictable way regardless of the state of the allocator.
+- The allocator's metadata size should be predictable based on the arena's size and not dependent on the state of the allocator.
+- The allocator's metadata location should be external to the arena.
+- Returned memory should be aligned to known and specified block size.
+
+The following were not design goals
+
+- To be used by multiple threads at the same time without additional locking.
+- To be a general purpose malloc() replacement.
+
+## Rationale
+
+### Why use a custom allocator (like buddy_alloc) ?
+
+A custom allocator is useful where there is no system allocator (e.g. on bare-metal) or when the system allocator does not meet some particular requirements, usually in terms of performance or features. The buddy_alloc custom allocator has bounded performance and bounded storage overhead for its metadata. The bounded performance is important in time-sensitive systems that must perform some action in a given amount of time. The bounded storage overhead is important for ensuring system reliability and allows for upfront system resource planing.
+
+A common example of systems that require both bound performance and bounded storage overhead from their components are games and gaming consoles. Games are time-sensitive in multiple aspects - they have to render frames fast to ensure a smooth display and sample input regularly to account for player input. But just fast is not enough - if an allocator is fast on average but occasionally an operation happens to be an order of magnitude slower this will impact both the display of the game as well as the input and may frustrate the player. Games and game consoles are also sensitive to their storage requirements - game consoles usually ship with fixed hardware and game developers have to optimize their games to perform well on the given machines.
+
+A custom allocator can supplement the system allocator where needed. A parser that is parsing some structured data (e.g. a json file) may need to allocate objects based on the input's structure. Using the system allocator for this is a risk as the parser may have a bug that causes it to allocate too much or the input may be crafted in such a way. Using a custom allocator with a fixed size for this sort of operations allows the operation to fail safely without impacting the application or the overall system stability.
+
+An application developer may also need object allocation that is relocatable. Using memory representation as serialization output is a valid technique and it is used for persistence and replication. The buddy_alloc embedded mode is relocatable allowing it to be serialized and restored to a different memory location, a different process or a different machine altogether (provided matching architecture and binaries).
+
+With the introduction of the `buddy_walk` function the allocator can be used to iterate all the allocated slots with its arena. This can be used for example for a space-bounded mailbox where a failure to allocate means the mailbox is full and the walk can be used to process its content. This can also form the basis of a managed heap for garbage collection.
+
+## Implementation
+
+```
++-------------+                  +----------------------------------------------------------+
+|             |                  | The allocator component works with 'struct buddy *' and  |
+|  allocator  +------------------+ is responsible for the allocator interface (malloc/free )|
+|             |                  | and for interfacing with the allocator tree.             |
++------+------+                  +----------------------------------------------------------+
+       |
+       |(uses)
+       |
++------v------+                   +------------------------------------------------------+
+|             |                   | The allocator tree is the core internal component.   |
+|  allocator  +-------------------+ It provides the actual allocation and deallocation   |
+|    tree     |                   | algorithms and uses a binary tree to keep its state. |
+|             |                   +------------------------------------------------------+
++------+------+
+       |
+       |(uses)
+       |
++------v------+                   +---------------------------------------------------+
+|             |                   | The bitset is the allocator tree backing store.   |
+|   bitset    +-------------------+                                                   |
+|             |                   | The buddy_tree_internal_position_* functions map  |
++-------------+                   | a tree position to the bitset.                    |
+                                  |                                                   |
+                                  | The write_to and read_from (internal position)    |
+                                  | functions encode and decode values in the bitset. |
+                                  |                                                   |
+                                  | Values are encoded in unary with no separators as |
+                                  | the struct internal_position lists their length.  |
+                                  | The unary encoding is faster to encode and decode |
+                                  | on unaligned boundaries.                          |
+                                  +---------------------------------------------------+
+```
+
+### Metadata
+
+The allocator uses a bitset-backed perfect binary tree to track allocations. The tree is fixed in size and remains outside of the main arena. This allows for better cache performance in the arena as the cache is not loading allocator metadata when processing application data.
+
+### Allocation and deallocation
+
+The binary tree nodes are labeled with the largest allocation slot available under them. This allows allocation to happen with a limited number of operations. Allocations that cannot be satisfied are fast to fail. Once a free node of the desired size is found it is marked as used and the nodes leading to root of the tree are updated to account for any difference in the largest available size. Deallocation works in a similar way - the allocated block size for the given address is found, marked as free and the same node update as with allocation is used to update the tree upwards. 
+
+#### Fragmentation
+
+To minimize fragmentation the allocator will pick the more heavily-used branches when descending the tree to find a free slot. This ensures that larger continuous spans are kept available for larger-sized allocation requests. A minor benefit is that clumping allocations together can allow for better cache performance.
+
+### Space requirements
+
+The tree is stored in a bitset with each node using just enough bits to store the maximum allocation slot available under it. For leaf nodes this is a single bit. Other nodes sizes depend on the height of the tree.
+
+### Non-power-of-two arena sizes
+
+The perfect binary tree always tracks an arena which size is a power-of-two. When the allocator is initialized or resized with an arena that is not a perfect fit the binary tree is updated to mask out the virtual arena complement to next power-of-two.
+
+### Resizing
+
+Resizing is available for both split and embedded allocator modes and supports both growing the arena and shrinking it. Checks are present that prevent shrinking the arena when memory that is to be reduced is still allocated.
+
+## Users
+
+If you are using buddy_alloc in your project and you would like project to be featured here please send a PR or file an issue. If you like buddy_alloc please star it on GitHub so that more users can learn of it. Thanks!
+
+- Use in game development - [1](https://github.com/spaskalev/buddy_alloc/issues/13#issue-1088282333), [2](https://github.com/fruityloops1/bf-multiplayer/commit/0c2599390566c7a3f174afc6f3c97b6b3efbeb2c)
+- Use in OS kernels - [1](https://github.com/Itay2805/pentagon/blob/1aa005a3f204f40b5869568bd78f4b3087e024a3/kernel/mem/phys.c#L28), [2](https://github.com/spaskalev/buddy_alloc/issues/76), [3](https://github.com/elydre/profanOS/commit/2d43930c36bdc4a5bead2312d7a629e36da4bd78)
+- Use in OS research - [1](https://repositories.lib.utexas.edu/server/api/core/bitstreams/ce9f9383-809a-4cc3-ba0b-e8a5e0428ef4/content), [2](https://www.cs.utexas.edu/~witchel/pubs/zhu24dimes-lupin.pdf), [3](https://upcommons.upc.edu/bitstream/handle/2117/411096/main.pdf;jsessionid=8D64ABBCE67117F7F2BB29A51B72CCCF)
+- Use in user-space software - [1](https://github.com/liulilittle/PPP-2/commit/6da093802ffa541ea4cf6f92b01ef783d493d706)
+- Use in scientific software - [1](https://github.com/ecmwf-ifs/field_api)
+
+<br>
+<br>
+
+
+[![ORG](https://img.shields.io/badge/org-nodef-green?logo=Org)](https://nodef.github.io)
+![](https://ga-beacon.deno.dev/G-RC63DPBH3P:SH3Eq-NoQ9mwgYeHWxu7cw/github.com/nodef/buddy_alloc.c)

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Please report all issues via [GitHub's issues page](https://github.com/spaskalev/buddy_alloc/issues).
+
+If your report contains confidential information you can use GitHub's private reporting of a security vulnerability as documented [here](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).