# 📚 Bookcase - An Arena Allocator
I wanted to learn arenas, so I implemented my own. Then I noticed the existing arena crates were not
to my liking.
## 🕐 Project Status
Experimental, do not use unless you are a 🤡.
## 📖 Glossary
- Person: thread
- Notebook: arena
- Chapter: set of commonly aligned pages
- Page: fixed sized buffer of raw bytes
- Utensil: implementation of allocation
Notebooks start out blank. A person can write into a notebook. Depending on if they use pencil or
pen, they may or may not be able to erase their notes. A person can pass a notebook to another
person. Any person can write in the notebook, but only one at a time. Any number of people can read
from a notebook at the same time.
This analogy is not perfect, but it's way better than what 'arena' has to offer! 😁
## 🎯 Goals
- Thread safe
- Safe interface
- Ergonomic
- Fast
- Lean
- Configurable
- Building block for data structures
- No external dependencies
- Documented
## 🚫 Concessions
- Unsafe implementation details
- Lookup is out of scope (this is not an ECS library)
## 🚀 Progress
In rough priority order:
- [ ] CI
- [ ] CD
- [x] No dependencies
- [ ] Well documented
- [x] Thread-local notebooks (`Personal*Notebook: Send`)
- [ ] Thread-safe notebooks (`Public*Notebook: Send + Sync`, very unsafe)
- [x] Bump allocation (`Pen`)
- [ ] Deallocation
- [x] Compiles on stable rust
- [x] Publish first experimental version
- [ ] Publish first beta version
- [ ] Publish first stable version
- [x] Heterogeneous notebook (`*MultiNotebook: Notebook`)
- [x] Homogeneous notebook (`*MonoNotebook<T>: TypedNotebook<T>`)
- [x] All allocations are aligned
- [ ] `*MultiNotebook: Allocator` (requires nightly)
- [x] Configurable page base size (`SizeStrategy`)
- [x] Configurable page growth rate (`GrowthStrategy`)
- [x] Non-dropping exclusive references (`alloc*() -> &mut T`)
- [x] Auto-dropping handles (`new*() -> Handle<T>`)
- [ ] Notebook merging
## 🌳 Versioning
### Philosophy
1. Backwards compatibility is falling asleep to the sound of ocean waves breaking on the beach.
2. *Assuming* backwards compatibility is torturing puppies.
**Conclusion: SemVer is 🐍🛢**
### Consequence
Unfortunately, cargo is tied to SemVer. Fortunately, SemVer is versioned. This means I can create my
own version of SemVer! 😈 Call it `SemVer Maggie.1.0`. Here's how it works:
### The Ironclad Rule
Assume all versions are breaking.
### The Motto
Strive to keep breaking changes to an absolute minimum.
### Release Channels
Each dot separated number represents a release channel:
###### Stable
This channel is the only one suitable for production use.
###### Beta
This channel is for collecting well baked ideas that are preparing for stabilization.
###### Experimental
This channel is the wild west where all bets are off and clown behavior is the norm.
#### Format: `stable.beta.experimental`
1. The version is in the experimental channel when `experimental > 0`, otherwise...
2. The version is in the beta channel when `beta > 0`, otherwise...
3. The version is in the stable channel when `stable > 0`, otherwise...
4. The version is invalid.
Therefore all stable releases are a bump to the "major" version suggesting to the downstream
developer they should consider The Ironclad Rule even if they are unfamiliar
with `SemVer Maggie.1.0`.
#### Examples
- `=1.0.0` - stable `v1`
- `=1.2.0` - beta `v2` based off stable `v1`
- `=1.2.3` - experimental `v3` based off beta `v2` based off stable `v1`
- `=2.0.1` - experimental `v1` based off stable `v2`
- `=0.0.0` - invalid
#### But I Like `bookcase_alloc = "^1"`!
Then get accustomed to compiler errors. A version within a release channel will only compile with
its respective feature enabled. The default feature is of course `stable`. Enabling more than one
will also fail to compile. This is to prevent accidental use of beta and experimental channels in
production user code.
### ... Maggie?
Maggie is my pet 🐷. She sucks at first, but you will eventually grow to love her.
### Exceptions
`bookcase_alloc_macros` is itself required to enforce the rules of `SemVer Maggie.1.0`. As such, it
will only have a stable release channel.
## Contribution
I created a [discord channel](https://discord.gg/VNjUtBh4UB). As of this writing it has a population
of me. Read the Goals, Concessions, and Progress sections for ideas on what to work on, and speak
with me about how to make changes I am likely to accept. You can also just ask questions and give me
feedback: feature requests, tell me my code is terrible or that I'm being too edgy. All feedback is
welcome!