{"id":17168588,"url":"https://github.com/jfrimmel/emballoc","last_synced_at":"2025-04-13T15:36:30.032Z","repository":{"id":57594459,"uuid":"526488277","full_name":"jfrimmel/emballoc","owner":"jfrimmel","description":"Simple but reliable memory allocator for embedded Rust and #![no_std]","archived":false,"fork":false,"pushed_at":"2023-11-14T18:40:23.000Z","size":89,"stargazers_count":5,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-14T14:45:02.757Z","etag":null,"topics":["allocator","embedded","no-std","rust","rust-no-std"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/emballoc","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jfrimmel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-19T06:28:37.000Z","updated_at":"2024-02-03T21:53:03.000Z","dependencies_parsed_at":"2024-09-17T20:58:21.556Z","dependency_job_id":"c58862ac-4552-46c6-aca8-c95c4caa47af","html_url":"https://github.com/jfrimmel/emballoc","commit_stats":{"total_commits":39,"total_committers":1,"mean_commits":39.0,"dds":0.0,"last_synced_commit":"4fbb0009e13388b6b63cbdc4bcf55c7829a4a335"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfrimmel%2Femballoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfrimmel%2Femballoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfrimmel%2Femballoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfrimmel%2Femballoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jfrimmel","download_url":"https://codeload.github.com/jfrimmel/emballoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248737575,"owners_count":21153794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["allocator","embedded","no-std","rust","rust-no-std"],"created_at":"2024-10-14T23:12:16.496Z","updated_at":"2025-04-13T15:36:30.009Z","avatar_url":"https://github.com/jfrimmel.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `emballoc` — Embedded Memory Allocator\n\n[![crates.io](https://img.shields.io/crates/v/emballoc)](https://crates.io/crates/emballoc)\n[![circleci](https://img.shields.io/circleci/build/github/jfrimmel/emballoc)](https://app.circleci.com/pipelines/github/jfrimmel/emballoc)\n[![codecov](https://codecov.io/gh/jfrimmel/emballoc/branch/main/graph/badge.svg?token=XU4EG0HGRP)](https://codecov.io/gh/jfrimmel/emballoc)\n[![docs.rs](https://img.shields.io/docsrs/emballoc)](https://docs.rs/emballoc)\n\nThis repository provides the [`emballoc`](https://crates.io/crates/emballoc) crate: a simple memory allocator developed for usage in small embedded systems.\nIt is one possible way to support dynamic memory on targets without the standard library, i.e. ones with `#![no_std]`.\nThis is achieved by providing a type [`Allocator`](https://docs.rs/emballoc/*/emballoc/struct.Allocator.html) which can be registered as the global allocator for the binary.\nSee the usage description below.\n\nAn allocator is a rather critical part of a software project:\nwhen using dynamic memory many operations implicitly can or will allocate, sometimes unexpectedly.\nTherefore a misbehaving allocator can \"randomly\" crash the program in very obscure ways.\nAs such an allocator has to be well-tested and battle-proven (see more information [here][docu-testing] and a [real world example][gist_hosted-test]).\nFurthermore it has to be _simple_: the simpler the algorithm is, the more likely is a correct implementation.\n\nRefer to the [crate-documentation](https://docs.rs/emballoc/) for details on the algorithm and usage hints.\n\n# Usage\n\nCopy the following snippet to your `Cargo.toml` to pull the crate in as one of your dependencies.\n\n```toml\n[dependencies.emballoc]\nversion = \"*\" # replace with current version from crates.io\n```\n\nAfter that the usage is very simple: just copy the following code to the binary crate of the project.\nSubstitute the `4096` with the desired heap size in bytes.\n\n```rust\n#[global_allocator]\nstatic ALLOCATOR: emballoc::Allocator\u003c4096\u003e = emballoc::Allocator::new();\n\nextern crate alloc;\n```\n\nNow the crate can use the `std` collections such as `Vec\u003cT\u003e`, `BTreeMap\u003cK, V\u003e`, etc. together with important types like `Box\u003cT\u003e` and `Rc\u003cT\u003e`.\nNote, that things in the `std`-prelude (e.g. `Vec\u003cT\u003e`, `Box\u003cT\u003e`, ...) have to be imported explicitly.\n\n# Why choosing this crate\n\nThis crate started as part of an embedded project, but was extracted to make it usable in other projects and for other users.\nThis sections answers the question:\n\n\u003e Why should you consider using this crate in your project?\n\n- the core algorithm is _simple_ and thus implementation errors are less likely\n- rigorous testing is done (see [here][docu-testing])\n- crate is free of undefined behavior according to `miri`\n- statically determined heap size preventing growing the heap into the stack\n- it is used in real-world applications\n- it even works on a PC (see [here][gist_hosted-test]), although that is not the primary use case\n- supports the stable compiler as there are only stable features used\n- has only a single dependency on the popular `spin`-crate (without any transitive dependencies)\n\nI'm glad, if that convinced you, but if you have any questions simply [open an issue](https://github.com/jfrimmel/emballoc/issues/new/choose).\n\nA note to users on systems with advanced memory features like MMUs and MPUs:\n\n- if you have an _memory protection unit_ (MPU) or similar available, you have to configure it yourself as this crate is platform-agnostic.\n  An example usage might be to configure it, that reading from and writing to the heap is allowed, but execution is not.\n  It is not necessary to surround the heap with guard pages, as this allocator will never read/write outside of the internal byte array.\n  However it might be advised to guard the stack, so that it doesn't grow into the heap (or any other variable).\n- if you have an (active) _memory management unit_ (MMU), this is likely not the crate for you: it doesn't use any of the important features, which makes it perform much worse than possible.\n  Use a proper memory allocator for that use case (one that supports paging, etc.).\n  However, if you need dynamic memory before enabling the MMU, this crate certainly is an option.\n\n# Platform support\n\nThis crate does not use any platform-specific features (e.g. an MMU or specific instructions), except for the requirement for a atomic compare-and-swap-instruction (CAS), which is widely available.\nTherefore this crate works out-of-the-box on most architectures.\n\nSome platforms however don't provide such an instruction (e.g. `thumbv6m-none-eabi` or the RISC-V OpenTitan) or totally lack atomic instructions (e.g. AVR) due to only a single-core nature.\nOn those platforms, where the CAS instruction is not available, one can use the workaround, that [`spin`][spin-docs] use: you can enable the `portable_atomic`-feature in your `Cargo.toml`, like this:\n```toml\n[dependencies.emballoc]\nversion = \"*\" # replace with current version from crates.io\nfeatures = [\"portable_atomic\"]\n```\nThis enables the use of the `portable_atomic` instead of the `core`-atomics.\nThis is safe on any platform.\n\nTo actually enable atomics support on platforms without hardware support, the `--cfg portable_atomic_unsafe_assume_single_core`-option needs to be explicitly enabled when compiling.\nFor more details see the [documentation of `spin`][spin-docs].\n\n# Minimum supported Rust version\n\nThis crate has a stability guarantee about the compiler version supported.\nThe so-called minimum supported Rust version is currently set to **1.57** and won't be raised without a proper increase in the semantic version number scheme.\nThis MSRV is specified in `Cargo.toml` and is tested in CI.\n\n# License\n\nLicensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))\n\nat your option.\n\n[docu-testing]: https://docs.rs/emballoc/latest/emballoc/#testing\n[gist_hosted-test]: https://gist.github.com/jfrimmel/61943f9879adfbe760a78efa17a0ecaa\n[spin-docs]: https://crates.io/crates/spin#Feature_flags\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfrimmel%2Femballoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfrimmel%2Femballoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfrimmel%2Femballoc/lists"}