o1heap 0.0.1

Rust bindings for o1heap - a constant-time deterministic memory allocator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# o1heap-rs

Rust bindings for [o1heap](https://github.com/pavel-kirienko/o1heap) - a constant-time deterministic memory allocator for hard real-time systems.

## Features

- **Constant-time O(1)** allocation and deallocation
- **Deterministic** behavior suitable for real-time systems
- **No-std** compatible - designed for embedded systems
- **Bounded fragmentation** - predictable memory usage
- **Safe Rust wrapper** with optional `GlobalAlloc` implementation

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
o1heap = "0.0.1"
```

For use as a global allocator:

```toml
[dependencies]
o1heap = { version = "0.0.1", features = ["global_alloc"] }
```

## Usage

### Basic Usage

```rust
use o1heap::O1Heap;
use core::mem::MaybeUninit;

// Create an aligned memory arena
#[repr(C, align(16))]
struct Arena([MaybeUninit<u8>; 4096]);

static mut ARENA: Arena = Arena([MaybeUninit::uninit(); 4096]);

fn main() {
    let heap = unsafe {
        O1Heap::new(ARENA.0.as_mut_ptr() as *mut _, 4096)
    }.expect("Failed to initialize heap");

    // Allocate memory
    let ptr = heap.allocate(64);
    if !ptr.is_null() {
        // Use allocated memory...
        
        // Free when done
        unsafe { heap.free(ptr) };
    }
}
```

### As Global Allocator

```rust
#![no_std]

extern crate alloc;

use o1heap::O1HeapGlobalAlloc;
use core::mem::MaybeUninit;

#[repr(C, align(16))]
struct Arena([MaybeUninit<u8>; 8192]);
static mut ARENA: Arena = Arena([MaybeUninit::uninit(); 8192]);

#[global_allocator]
static HEAP: O1HeapGlobalAlloc = O1HeapGlobalAlloc::new();

fn init_heap() {
    unsafe { 
        HEAP.init(ARENA.0.as_mut_ptr() as *mut _, 8192) 
    }.expect("heap init failed");
}

fn main() {
    init_heap();
    
    // Now you can use alloc types like Box, Vec, etc.
    let boxed = alloc::boxed::Box::new(42);
}
```

## Alignment

o1heap guarantees that all allocated memory is aligned to `O1HEAP_ALIGNMENT`:
- **32-bit systems**: 16 bytes
- **64-bit systems**: 32 bytes

This alignment is available as `o1heap::ALIGNMENT`.

## Minimum Arena Size

The minimum arena size can be queried at runtime with `o1heap::min_arena_size()`. This is typically around 192 bytes on 32-bit systems.

## Diagnostics

```rust
let diag = heap.diagnostics();
println!("Capacity: {}", diag.capacity);
println!("Allocated: {}", diag.allocated);
println!("Peak allocated: {}", diag.peak_allocated);
println!("OOM count: {}", diag.oom_count);

// Runtime invariant check
assert!(heap.invariants_hold());
```

## Thread Safety

o1heap is **not thread-safe**. If you need to use it from multiple threads or interrupt contexts, you must provide external synchronization (e.g., critical sections, mutexes).

## License

This crate is licensed under the MIT license. The underlying [o1heap](https://github.com/pavel-kirienko/o1heap) C library is Copyright (c) Pavel Kirienko and also MIT licensed.

## Credits

- [o1heap](https://github.com/pavel-kirienko/o1heap) by Pavel Kirienko