https://github.com/barbell-math/smoothbrain-arena
A very simple library that implements an arena allocator in 100% golang.
https://github.com/barbell-math/smoothbrain-arena
arena arena-allocator golang golang-library golang-package
Last synced: about 1 year ago
JSON representation
A very simple library that implements an arena allocator in 100% golang.
- Host: GitHub
- URL: https://github.com/barbell-math/smoothbrain-arena
- Owner: barbell-math
- License: mit
- Created: 2025-04-24T23:49:06.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-05T01:47:13.000Z (about 1 year ago)
- Last Synced: 2025-06-10T00:47:21.097Z (about 1 year ago)
- Topics: arena, arena-allocator, golang, golang-library, golang-package
- Language: Go
- Homepage:
- Size: 21.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# sbarena
```go
import "github.com/barbell-math/smoothbrain-arena"
```
A very simple library that implements an arena allocator in 100% golang.
## Index
- [Constants](<#constants>)
- [Variables](<#variables>)
- [func Alloc\[T any\]\(a \*Arena\) \(weak.Pointer\[T\], error\)](<#Alloc>)
- [func BucketSizeBytes\(a \*Arena\) uintptr](<#BucketSizeBytes>)
- [func Clear\(a \*Arena\)](<#Clear>)
- [func NumBuckets\(a \*Arena\) int](<#NumBuckets>)
- [func Reset\(a \*Arena\)](<#Reset>)
- [func TotalMemBytes\(a \*Arena\) uintptr](<#TotalMemBytes>)
- [type Arena](<#Arena>)
- [func NewArena\(bucketSizeBytes uintptr\) Arena](<#NewArena>)
## Constants
```go
const (
// 64 Kib. The default bucket size used when a bucket size <=0 is supplied
// to [NewArena].
DefaultBlockSize uintptr = 65536
)
```
## Variables
```go
var (
ValueToLargeErr = errors.New(
"The supplied value was to large to place in the arena",
)
)
```
```go
func Alloc[T any](a *Arena) (weak.Pointer[T], error)
```
Allocates enough space in the arena to hold a value of type T. The size of T must be less than the bucket size the allocator was initialized with, otherwise a [ValueToLargeErr](<#ValueToLargeErr>) will be returned.
```go
func BucketSizeBytes(a *Arena) uintptr
```
Returns the bucket size for the given arena.
```go
func Clear(a *Arena)
```
Frees all of the memory that the arena allocated. Calling this function will cause all other pointers that reference this arenas memory to be set to nil.
The arena can still be used after this operation, it will allocate more memory as needed. If this arena is used to allocate more memory the old memory will not be reused.
```go
func NumBuckets(a *Arena) int
```
Gets the number of buckets that the arena has currently allocated.
```go
func Reset(a *Arena)
```
Resets the internal state of the arena so that it starts to reuse memory, overwriting the memory it previously used.
No new memory will be allocated and as such all other pointers that reference this arenas memory can still be used, though they are no longer guaranteed to point to valid values.
```go
func TotalMemBytes(a *Arena) uintptr
```
Returns the total number of bytes the arena has allocated across all buckets.
A dynamic arena allocator that is backed by buckets. Objects that are larger than the bucket size cannot be stored in the area. The bucket size can be specified when calling [NewArena](<#NewArena>).
An Arena must \*not\* be copied by value, this will invalidate the atomics protecting allocation operations.
Go is a GC'ed language, so you cannot control exactly when the GC will free the arena but when it does all of the objects that it stores will be freed along with it. The GC cleaning up the Arena struct is equivalent to freeing all of the memory.
An Arena is thread safe for allocations and frees, though once the arena is freed all pointers to the data it contained will be invalidated and set to nil.
```go
type Arena struct {
// contains filtered or unexported fields
}
```
```go
func NewArena(bucketSizeBytes uintptr) Arena
```
Creates a new [Arena](<#Arena>) allocator, initializing it to use \`bucketSizeBytes\` bucket size.
Generated by [gomarkdoc]()
## Helpful Developer Cmds
To build the build system:
```
go build -o ./bs/bs ./bs
```
The build system can then be used as usual:
```
./bs/bs --help
./bs/bs buildbs # Builds the build system!
```