A platform agnostic way to reserve/commit/decommit virtual memory. virtual.Arena usage Example: // Source: https://github.com/odin-lang/examples/blob/master/arena_allocator/arena_allocator.odin import "core:fmt" import "core:os" // virtual package implements a multi-purpose arena allocator. If you are on a // platform that does not support virtual memory, then there is also a similar // arena in `core:mem`. import vmem "core:mem/virtual" load_files :: proc() -> ([]string, vmem.Arena) { // This creates a growing virtual memory arena. It uses virtual memory and // can grow as things are added to it. arena: vmem.Arena arena_err := vmem.arena_init_growing(&arena) ensure(arena_err == nil) arena_alloc := vmem.arena_allocator(&arena) // See arena_init_static for an arena that uses virtual memory, but cannot grow. // See arena_init_buffer for an arena that does not use virtual memory, // instead it relies on you feeding it a buffer. f1, f1_err := os.read_entire_file("file1.txt", arena_alloc) ensure(f1_err == nil) f2, f2_err := os.read_entire_file("file2.txt", arena_alloc) ensure(f2_err == nil) f3, f3_err := os.read_entire_file("file3.txt", arena_alloc) ensure(f3_err == nil) res := make([]string, 3, arena_alloc) res[0] = string(f1) res[1] = string(f2) res[2] = string(f3) return res, arena } main :: proc() { files, arena := load_files() for f in files { fmt.println(f) } // This deallocates everything that was allocated on the arena: // The loaded content of the files as well as the `files` slice. vmem.arena_destroy(&arena) } virtual.map_file usage Example: // Source: https://github.com/odin-lang/examples/blob/master/arena_allocator/arena_allocator.odin import "core:fmt" // virtual package implements cross-platform file memory mapping import vmem "core:mem/virtual" main :: proc() { data, err := vmem.map_file_from_path(#file, {.Read}) defer vmem.unmap_file(data) fmt.printfln("Error: %v", err) fmt.printfln("Data: %s", data) }

Collection Info

View Source
Collection
core
Path
mem/virtual
Entries
58
Constants 5
Jump to Constants
DEFAULT_ARENA_GROWING_COMMIT_SIZE DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE DEFAULT_ARENA_STATIC_COMMIT_SIZE DEFAULT_ARENA_STATIC_RESERVE_SIZE Protect_No_Access
Types 12
Jump to Types
Allocator_Error Arena Arena_Kind Arena_Temp Map_File_Error Map_File_Flag Map_File_Flags Memory_Block Memory_Block_Flag Memory_Block_Flags Protect_Flag Protect_Flags
Procedures 36
Jump to Procedures
alloc_from_memory_block arena_alloc arena_allocator arena_allocator_proc arena_check_temp arena_destroy arena_free_all arena_growing_bootstrap_new_by_name arena_growing_bootstrap_new_by_offset arena_growing_free_last_memory_block arena_init_buffer arena_init_growing arena_init_static arena_static_bootstrap_new_by_name arena_static_bootstrap_new_by_offset arena_static_reset_to +20 more
Procedure Groups 4
Jump to Procedure Groups
arena_growing_bootstrap_new arena_static_bootstrap_new make map_file
Variables 1
Jump to Variables
DEFAULT_PAGE_SIZE

Source Files

(hidden platform specific files)

Constants

5

DEFAULT_ARENA_GROWING_COMMIT_SIZE #

Source 
DEFAULT_ARENA_GROWING_COMMIT_SIZE :: 8 * mem.Megabyte

DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE #

Source 
DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE :: DEFAULT_ARENA_STATIC_COMMIT_SIZE

DEFAULT_ARENA_STATIC_COMMIT_SIZE #

Source 
DEFAULT_ARENA_STATIC_COMMIT_SIZE :: mem.Megabyte

1 MiB should be enough to start with

DEFAULT_ARENA_STATIC_RESERVE_SIZE #

Source 
DEFAULT_ARENA_STATIC_RESERVE_SIZE :: mem.Gigabyte when size_of(uintptr) == 8 else 128 * mem.Megabyte

1 GiB on 64-bit systems, 128 MiB on 32-bit systems by default

Types

12

Arena #

Source 
Arena :: Arena

Arena is a generalized arena allocator that supports 3 different variants. Growing: A linked list of `Memory_Block`s allocated with virtual memory. Static: A single `Memory_Block` allocated with virtual memory. Buffer: A single `Memory_Block` created from a user provided []byte.

Arena_Temp #

Source 
Arena_Temp :: Arena_Temp

An `Arena_Temp` is a way to produce temporary watermarks to reset an arena to a previous state. All uses of an `Arena_Temp` must be handled by ending them with `arena_temp_end` or ignoring them with `arena_temp_ignore`.

Procedures

36

arena_alloc #

Source 
@(require_results)
@(no_sanitize_address)
arena_alloc :: proc(arena: ^Arena, size: uint, alignment: uint, loc := #caller_location) -> (data: []u8, err: Allocator_Error) {…}

Allocates memory from the provided arena.

arena_allocator #

Source 
@(require_results)
@(no_sanitize_address)
arena_allocator :: proc(arena: ^Arena) -> Allocator {…}

Create an `Allocator` from the provided `Arena`

arena_allocator_proc #

Source 
@(no_sanitize_address)
arena_allocator_proc :: proc(
	allocator_data:  rawptr, 
	mode:            Allocator_Mode, 
	size, alignment: int, 
	old_memory:      rawptr, 
	old_size:        int, 
	location := #caller_location, 
) -> (data: []u8, err: Allocator_Error) {…}

The allocator procedure used by an `Allocator` produced by `arena_allocator`

arena_check_temp #

Source 
@(no_sanitize_address)
arena_check_temp :: proc(arena: ^Arena, loc := #caller_location) {…}

Asserts that all uses of `Arena_Temp` has been used by an `Arena`

arena_destroy #

Source 
@(no_sanitize_address)
arena_destroy :: proc(arena: ^Arena, loc := #caller_location) {…}

Frees all of the memory allocated by the arena and zeros all of the values of an arena. A buffer based arena does not `delete` the provided `[]byte` bufffer.

arena_free_all #

Source 
@(no_sanitize_address)
arena_free_all :: proc(arena: ^Arena, loc := #caller_location) {…}

Deallocates all but the first memory block of the arena and resets the allocator's usage to 0.

arena_growing_bootstrap_new_by_name #

Source 
@(require_results)
@(no_sanitize_address)
arena_growing_bootstrap_new_by_name :: proc($T: typeid, $field_name: string, minimum_block_size: uint = DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE) -> (ptr: ^typeid, err: Allocator_Error) {…}

Ability to bootstrap allocate a struct with an arena within the struct itself using the growing variant strategy.

arena_growing_bootstrap_new_by_offset #

Source 
@(require_results)
@(no_sanitize_address)
arena_growing_bootstrap_new_by_offset :: proc($T: typeid, offset_to_arena: uintptr, minimum_block_size: uint = DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE) -> (ptr: ^typeid, err: Allocator_Error) {…}

Ability to bootstrap allocate a struct with an arena within the struct itself using the growing variant strategy.

arena_growing_free_last_memory_block #

Source 
@(no_sanitize_address)
arena_growing_free_last_memory_block :: proc(arena: ^Arena, loc := #caller_location) {…}

Frees the last memory block of a Growing Arena

arena_init_buffer #

Source 
@(require_results)
@(no_sanitize_address)
arena_init_buffer :: proc(arena: ^Arena, buffer: []u8) -> (err: Allocator_Error) {…}

Initialization of an `Arena` to be a `.Buffer` variant. A buffer arena contains single `Memory_Block` created from a user provided []byte.

arena_init_growing #

Source 
@(require_results)
@(no_sanitize_address)
arena_init_growing :: proc(arena: ^Arena, reserved: uint = DEFAULT_ARENA_GROWING_MINIMUM_BLOCK_SIZE) -> (err: Allocator_Error) {…}

Initialization of an `Arena` to be a `.Growing` variant. A growing arena is a linked list of `Memory_Block`s allocated with virtual memory.

arena_init_static #

Source 
@(require_results)
@(no_sanitize_address)
arena_init_static :: proc(arena: ^Arena, reserved: uint = DEFAULT_ARENA_STATIC_RESERVE_SIZE, commit_size: uint = DEFAULT_ARENA_STATIC_COMMIT_SIZE) -> (err: Allocator_Error) {…}

Initialization of an `Arena` to be a `.Static` variant. A static arena contains a single `Memory_Block` allocated with virtual memory.

arena_static_bootstrap_new_by_name #

Source 
@(require_results)
@(no_sanitize_address)
arena_static_bootstrap_new_by_name :: proc($T: typeid, $field_name: string, reserved: uint) -> (ptr: ^typeid, err: Allocator_Error) {…}

Ability to bootstrap allocate a struct with an arena within the struct itself using the static variant strategy.

arena_static_bootstrap_new_by_offset #

Source 
@(require_results)
@(no_sanitize_address)
arena_static_bootstrap_new_by_offset :: proc($T: typeid, offset_to_arena: uintptr, reserved: uint) -> (ptr: ^typeid, err: Allocator_Error) {…}

Ability to bootstrap allocate a struct with an arena within the struct itself using the static variant strategy.

arena_static_reset_to #

Source 
@(no_sanitize_address)
arena_static_reset_to :: proc(arena: ^Arena, pos: uint, loc := #caller_location) -> bool {…}

Resets the memory of a Static or Buffer arena to a specific `position` (offset) and zeroes the previously used memory.

arena_temp_begin #

Source 
@(require_results)
@(no_sanitize_address)
arena_temp_begin :: proc(arena: ^Arena, loc := #caller_location) -> (temp: Arena_Temp) {…}

Begins the section of temporary arena memory.

arena_temp_end #

Source 
@(no_sanitize_address)
arena_temp_end :: proc(temp: Arena_Temp, loc := #caller_location) {…}

Ends the section of temporary arena memory by resetting the memory to the stored position.

arena_temp_ignore #

Source 
@(no_sanitize_address)
arena_temp_ignore :: proc(temp: Arena_Temp, loc := #caller_location) {…}

Ignore the use of a `arena_temp_begin` entirely by __not__ resetting to the stored position.

make_aligned #

Source 
@(require_results)
make_aligned :: proc(arena: ^Arena, $T: typeid/[]$E, #any_int len: int, alignment: uint, loc := #caller_location) -> ($$deferred_return, Allocator_Error) {…}

`make_aligned` allocates and initializes a slice. Like `new`, the second argument is a type, not a value. Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it. Note: Prefer using the procedure group `make`.

make_multi_pointer #

Source 
@(require_results)
make_multi_pointer :: proc(arena: ^Arena, $T: typeid/[^]$E, #any_int len: int, loc := #caller_location) -> ($$deferred_return, Allocator_Error) {…}

`make_multi_pointer` allocates and initializes a dynamic array. Like `new`, the second argument is a type, not a value. Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it. This is "similar" to doing `raw_data(make([]E, len, allocator))`. Note: Prefer using the procedure group `make`.

make_slice #

Source 
@(require_results)
make_slice :: proc(arena: ^Arena, $T: typeid/[]$E, #any_int len: int, loc := #caller_location) -> ($$deferred_return, Allocator_Error) {…}

`make_slice` allocates and initializes a slice. Like `new`, the second argument is a type, not a value. Unlike `new`, `make`'s return value is the same as the type of its argument, not a pointer to it. Note: Prefer using the procedure group `make`.

new #

Source 
@(require_results)
new :: proc(arena: ^Arena, $T: typeid, loc := #caller_location) -> (ptr: ^typeid, err: Allocator_Error) {…}

The `new` procedure allocates memory for a type `T` from a `virtual.Arena`. The second argument is a type, not a value, and the value return is a pointer to a newly allocated value of that type using the specified allocator.

new_aligned #

Source 
@(require_results)
new_aligned :: proc(arena: ^Arena, $T: typeid, alignment: uint, loc := #caller_location) -> (ptr: ^typeid, err: Allocator_Error) {…}

The `new_aligned` procedure allocates memory for a type `T` from a `virtual.Arena` with a specified `alignment`. The second argument is a type, not a value, and the value return is a pointer to a newly allocated value of that type using the specified allocator.

new_clone #

Source 
@(require_results)
new_clone :: proc(arena: ^Arena, data: $T, loc := #caller_location) -> (ptr: $$deferred_return, err: Allocator_Error) {…}

The `new_clone` procedure allocates memory for a type `T` from a `virtual.Arena`. The second argument is a value that is to be copied to the allocated data. The value returned is a pointer to a newly allocated value of that type using the specified allocator.

Procedure Groups

4

Variables

1