This file contains the structures and functions of the memory system. This is responsible for memory interaction with the platform layer, such as allocations/frees and tagging of memory allocations. More...

#include "defines.h"

Data Structures
struct	frame_allocator_int

struct	memory_system_configuration
	The configuration for the memory system. More...

Macros
#define	KALLOC_TYPE(type, mem_tag) (type*)kallocate(sizeof(type), mem_tag)
	Dynamically allocates memory for the given type. Also casts to type*. More...

#define	KFREE_TYPE(block, type, mem_tag) kfree(block, sizeof(type), mem_tag)
	Frees the given dynamically-allocated memory of the provided type, using the given tag. More...

#define	KALLOC_TYPE_CARRAY(type, count) (type)kallocate(sizeof(type) count, MEMORY_TAG_ARRAY)
	Dynamically allocates memory for a standard C array of the given type. Also casts to type*. Memory is tagged as MEMORY_TAG_ARRAY. More...

#define	KFREE_TYPE_CARRAY(block, type, count) kfree(block, sizeof(type) * count, MEMORY_TAG_ARRAY)
	Frees the given dynamically-allocated array of the provided type, using MEMORY_TAG_ARRAY. More...

#define	KRESIZE_ARRAY(array, type, old_count, new_count)
	Resizes the given array of the provided type, also copying the contents of the old array to the new. Performs a new allocation, so the array address will be different. NOTE: new_count must be greater than old_count. More...

#define	KREALLOC_TYPE_CARRAY(block, type, old_count, new_count) (type)kreallocate(block, sizeof(type) old_count, sizeof(type) * new_count, MEMORY_TAG_ARRAY)
	Dynamically reallocates memory for a standard C array of the given type. Also casts to type*. Memory is tagged as MEMORY_TAG_ARRAY. More...

#define	KCOPY_TYPE(dest, source, type) kcopy_memory(dest, source, sizeof(type))

#define	KCOPY_TYPE_CARRAY(dest, source, type, count) kcopy_memory(dest, source, sizeof(type) * count)

Typedefs
typedef struct frame_allocator_int	frame_allocator_int

typedef enum memory_tag	memory_tag
	Tags to indicate the usage of memory allocations made in this system. More...

typedef struct memory_system_configuration	memory_system_configuration
	The configuration for the memory system. More...

Enumerations
enum	memory_tag { MEMORY_TAG_UNKNOWN , MEMORY_TAG_ARRAY , MEMORY_TAG_LINEAR_ALLOCATOR , MEMORY_TAG_DARRAY , MEMORY_TAG_DICT , MEMORY_TAG_RING_QUEUE , MEMORY_TAG_BST , MEMORY_TAG_STRING , MEMORY_TAG_ENGINE , MEMORY_TAG_JOB , MEMORY_TAG_TEXTURE , MEMORY_TAG_MATERIAL_INSTANCE , MEMORY_TAG_RENDERER , MEMORY_TAG_GAME , MEMORY_TAG_TRANSFORM , MEMORY_TAG_ENTITY , MEMORY_TAG_ENTITY_NODE , MEMORY_TAG_SCENE , MEMORY_TAG_RESOURCE , MEMORY_TAG_VULKAN , MEMORY_TAG_VULKAN_EXT , MEMORY_TAG_DIRECT3D , MEMORY_TAG_OPENGL , MEMORY_TAG_GPU_LOCAL , MEMORY_TAG_BITMAP_FONT , MEMORY_TAG_SYSTEM_FONT , MEMORY_TAG_KEYMAP , MEMORY_TAG_HASHTABLE , MEMORY_TAG_UI , MEMORY_TAG_AUDIO , MEMORY_TAG_REGISTRY , MEMORY_TAG_PLUGIN , MEMORY_TAG_PLATFORM , MEMORY_TAG_SERIALIZER , MEMORY_TAG_ASSET , MEMORY_TAG_MAX_TAGS }
	Tags to indicate the usage of memory allocations made in this system. More...

Functions
KAPI b8	memory_system_initialize (memory_system_configuration config)
	Initializes the memory system. More...

KAPI void	memory_system_shutdown (void)
	Shuts down the memory system. More...

KAPI void *	kallocate (u64 size, memory_tag tag)
	Performs a memory allocation from the host of the given size. The allocation is tracked for the provided tag. More...

KAPI void *	kallocate_aligned (u64 size, u16 alignment, memory_tag tag)
	Performs an aligned memory allocation from the host of the given size and alignment. The allocation is tracked for the provided tag. NOTE: Memory allocated this way must be freed using kfree_aligned. More...

KAPI void	kallocate_report (u64 size, memory_tag tag)
	Reports an allocation associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track allocations but not perform them. More...

KAPI void *	kreallocate (void *block, u64 old_size, u64 new_size, memory_tag tag)
	Performs a memory reallocation from the host of the given size, and also frees the block of memory given. The reallocation is tracked for the provided tag. More...

KAPI void *	kreallocate_aligned (void *block, u64 old_size, u64 new_size, u16 alignment, memory_tag tag)
	Performs a memory reallocation from the host of the given size and alignment, and also frees the block of memory given. The reallocation is tracked for the provided tag. NOTE: Memory allocated this way must be freed using kfree_aligned. More...

KAPI void	kreallocate_report (u64 old_size, u64 new_size, memory_tag tag)
	Reports an allocation associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track allocations but not perform them. More...

KAPI void	kfree (void *block, u64 size, memory_tag tag)
	Frees the given block, and untracks its size from the given tag. More...

KAPI void	kfree_aligned (void *block, u64 size, u16 alignment, memory_tag tag)
	Frees the given block, and untracks its size from the given tag. More...

KAPI void	kfree_report (u64 size, memory_tag tag)
	Reports a free associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track frees but not perform them. More...

KAPI b8	kmemory_get_size_alignment (void block, u64 out_size, u16 *out_alignment)
	Returns the size and alignment of the given block of memory. NOTE: A failure result from this method most likely indicates heap corruption. More...

KAPI void *	kzero_memory (void *block, u64 size)
	Zeroes out the provided memory block. More...

KAPI void *	kcopy_memory (void dest, const void source, u64 size)
	Performs a copy of the memory at source to dest of the given size. More...

KAPI void *	kset_memory (void *dest, i32 value, u64 size)
	Sets the bytes of memory located at dest to value over the given size. More...

KAPI char *	get_memory_usage_str (void)
	Obtains a string containing a "printout" of memory usage, categorized by memory tag. The memory should be freed by the caller. More...

KAPI u64	get_memory_alloc_count (void)
	Obtains the number of times kallocate was called since the memory system was initialized. More...

KAPI u32	pack_u8_into_u32 (u8 x, u8 y, u8 z, u8 w)
	Packs the values of 4 u8s into a single u32. More...

KAPI b8	unpack_u8_from_u32 (u32 n, u8 x, u8 y, u8 z, u8 w)
	Attempts to unpack 4 u8s from a u32. More...

Detailed Description

This file contains the structures and functions of the memory system. This is responsible for memory interaction with the platform layer, such as allocations/frees and tagging of memory allocations.

Author: Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Note: Note that reliance on this will likely be by core systems only, as items using allocations directly will use allocators as they are added to the system.

Version: 1.0

Date: 2022-01-10

Copyright: Kohi Game Engine is Copyright (c) Travis Vroman 2021-2022

Macro Definition Documentation

◆ KALLOC_TYPE

#define KALLOC_TYPE	(	type,
		mem_tag
	)	(type*)kallocate(sizeof(type), mem_tag)

Dynamically allocates memory for the given type. Also casts to type*.

Parameters

type	The type to be used when determining allocation size.
mem_tag	The memory tag to be used for the allocation.

◆ KALLOC_TYPE_CARRAY

#define KALLOC_TYPE_CARRAY	(	type,
		count
	)	(type)kallocate(sizeof(type) count, MEMORY_TAG_ARRAY)

Dynamically allocates memory for a standard C array of the given type. Also casts to type*. Memory is tagged as MEMORY_TAG_ARRAY.

Parameters

type	The type to be used when determining allocation size.
count	The number of elements existing in the array.

◆ KCOPY_TYPE

#define KCOPY_TYPE	(	dest,
		source,
		type
	)	kcopy_memory(dest, source, sizeof(type))

◆ KCOPY_TYPE_CARRAY

#define KCOPY_TYPE_CARRAY	(	dest,
		source,
		type,
		count
	)	kcopy_memory(dest, source, sizeof(type) * count)

◆ KFREE_TYPE

#define KFREE_TYPE	(	block,
		type,
		mem_tag
	)	kfree(block, sizeof(type), mem_tag)

Frees the given dynamically-allocated memory of the provided type, using the given tag.

Parameters

block	The block of memory to be freed.
type	The type to be used when determining allocation size.
mem_tag	The memory tag to be used for the deallocation.

◆ KFREE_TYPE_CARRAY

#define KFREE_TYPE_CARRAY	(	block,
		type,
		count
	)	kfree(block, sizeof(type) * count, MEMORY_TAG_ARRAY)

Frees the given dynamically-allocated array of the provided type, using MEMORY_TAG_ARRAY.

Parameters

block	The block of memory to be freed.
type	The type to be used when determining allocation size.
count	The number of elements in the array to be freed.

◆ KREALLOC_TYPE_CARRAY

#define KREALLOC_TYPE_CARRAY	(	block,
		type,
		old_count,
		new_count
	)	(type)kreallocate(block, sizeof(type) old_count, sizeof(type) * new_count, MEMORY_TAG_ARRAY)

Dynamically reallocates memory for a standard C array of the given type. Also casts to type*. Memory is tagged as MEMORY_TAG_ARRAY.

Parameters

block	The block of memory to reallocate.
type	The type to be used when determining allocation size.
old_count	The number of elements existing in the array.
new_count	The number of elements in the resized array.

◆ KRESIZE_ARRAY

#define KRESIZE_ARRAY	(	array,
		type,
		old_count,
		new_count
	)

Value:

    {                                                        \
        type* temp = KALLOC_TYPE_CARRAY(type, new_count);    \
        if (old_count && array) {                            \
            KCOPY_TYPE_CARRAY(temp, array, type, old_count); \
            KFREE_TYPE_CARRAY(array, type, old_count);       \
        }                                                    \
        array = temp;                                        \
    }

Resizes the given array of the provided type, also copying the contents of the old array to the new. Performs a new allocation, so the array address will be different. NOTE: new_count must be greater than old_count.

Typedef Documentation

◆ frame_allocator_int

typedef struct frame_allocator_int frame_allocator_int

◆ memory_system_configuration

typedef struct memory_system_configuration memory_system_configuration

The configuration for the memory system.

◆ memory_tag

typedef enum memory_tag memory_tag

Tags to indicate the usage of memory allocations made in this system.

Enumeration Type Documentation

◆ memory_tag

enum memory_tag

Tags to indicate the usage of memory allocations made in this system.

Enumerator
MEMORY_TAG_UNKNOWN
MEMORY_TAG_ARRAY
MEMORY_TAG_LINEAR_ALLOCATOR
MEMORY_TAG_DARRAY
MEMORY_TAG_DICT
MEMORY_TAG_RING_QUEUE
MEMORY_TAG_BST
MEMORY_TAG_STRING
MEMORY_TAG_ENGINE
MEMORY_TAG_JOB
MEMORY_TAG_TEXTURE
MEMORY_TAG_MATERIAL_INSTANCE
MEMORY_TAG_RENDERER
MEMORY_TAG_GAME
MEMORY_TAG_TRANSFORM
MEMORY_TAG_ENTITY
MEMORY_TAG_ENTITY_NODE
MEMORY_TAG_SCENE
MEMORY_TAG_RESOURCE
MEMORY_TAG_VULKAN
MEMORY_TAG_VULKAN_EXT
MEMORY_TAG_DIRECT3D
MEMORY_TAG_OPENGL
MEMORY_TAG_GPU_LOCAL
MEMORY_TAG_BITMAP_FONT
MEMORY_TAG_SYSTEM_FONT
MEMORY_TAG_KEYMAP
MEMORY_TAG_HASHTABLE
MEMORY_TAG_UI
MEMORY_TAG_AUDIO
MEMORY_TAG_REGISTRY
MEMORY_TAG_PLUGIN
MEMORY_TAG_PLATFORM
MEMORY_TAG_SERIALIZER
MEMORY_TAG_ASSET
MEMORY_TAG_MAX_TAGS

Function Documentation

◆ get_memory_alloc_count()

KAPI u64 get_memory_alloc_count ( void )

Obtains the number of times kallocate was called since the memory system was initialized.

Returns: The total count of allocations since the system's initialization.

◆ get_memory_usage_str()

KAPI char* get_memory_usage_str ( void )

Obtains a string containing a "printout" of memory usage, categorized by memory tag. The memory should be freed by the caller.

Deprecated:: This function should be discontinued in favour of something more robust in the future.

Returns: A pointer to a character array containing the string representation of memory usage.

◆ kallocate()

KAPI void* kallocate	(	u64	size,
		memory_tag	tag
	)

Performs a memory allocation from the host of the given size. The allocation is tracked for the provided tag.

Parameters

size	The size of the allocation.
tag	Indicates the use of the allocated block.

Returns: If successful, a pointer to a block of allocated memory; otherwise 0.

◆ kallocate_aligned()

KAPI void* kallocate_aligned	(	u64	size,
		u16	alignment,
		memory_tag	tag
	)

Performs an aligned memory allocation from the host of the given size and alignment. The allocation is tracked for the provided tag. NOTE: Memory allocated this way must be freed using kfree_aligned.

Parameters

size	The size of the allocation.
alignment	The alignment in bytes.
tag	Indicates the use of the allocated block.

Returns: If successful, a pointer to a block of allocated memory; otherwise 0.

◆ kallocate_report()

KAPI void kallocate_report	(	u64	size,
		memory_tag	tag
	)

Reports an allocation associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track allocations but not perform them.

Parameters

size	The size of the allocation.
tag	Indicates the use of the allocated block.

◆ kcopy_memory()

KAPI void* kcopy_memory	(	void *	dest,
		const void *	source,
		u64	size
	)

Performs a copy of the memory at source to dest of the given size.

Parameters

dest	A pointer to the destination block of memory to copy to.
source	A pointer to the source block of memory to copy from.
size	The amount of memory in bytes to be copied over.

Returns: A pointer to the block of memory copied to.

◆ kfree()

KAPI void kfree	(	void *	block,
		u64	size,
		memory_tag	tag
	)

Frees the given block, and untracks its size from the given tag.

Parameters

block	A pointer to the block of memory to be freed.
size	The size of the block to be freed.
tag	The tag indicating the block's use.

◆ kfree_aligned()

KAPI void kfree_aligned	(	void *	block,
		u64	size,
		u16	alignment,
		memory_tag	tag
	)

Frees the given block, and untracks its size from the given tag.

Parameters

block	A pointer to the block of memory to be freed.
size	The size of the block to be freed.
tag	The tag indicating the block's use.

◆ kfree_report()

KAPI void kfree_report	(	u64	size,
		memory_tag	tag
	)

Reports a free associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track frees but not perform them.

Parameters

size	The size in bytes.
tag	The tag indicating the block's use.

◆ kmemory_get_size_alignment()

KAPI b8 kmemory_get_size_alignment	(	void *	block,
		u64 *	out_size,
		u16 *	out_alignment
	)

Returns the size and alignment of the given block of memory. NOTE: A failure result from this method most likely indicates heap corruption.

Parameters

block	The memory block.
out_size	A pointer to hold the size of the block.
out_alignment	A pointer to hold the alignment of the block.

Returns: True on success; otherwise false.

◆ kreallocate()

KAPI void* kreallocate	(	void *	block,
		u64	old_size,
		u64	new_size,
		memory_tag	tag
	)

Performs a memory reallocation from the host of the given size, and also frees the block of memory given. The reallocation is tracked for the provided tag.

Parameters

block	The block of memory to reallocate.
old_size	The size of the old allocation (that gets freed).
new_size	The size of the new allocation (that get allocated).
tag	Indicates the use of the allocated block.

Returns: If successful, a pointer to a block of allocated memory; otherwise 0.

◆ kreallocate_aligned()

KAPI void* kreallocate_aligned	(	void *	block,
		u64	old_size,
		u64	new_size,
		u16	alignment,
		memory_tag	tag
	)

Performs a memory reallocation from the host of the given size and alignment, and also frees the block of memory given. The reallocation is tracked for the provided tag. NOTE: Memory allocated this way must be freed using kfree_aligned.

Parameters

block	The block of memory to reallocate.
old_size	The size of the old allocation (that gets freed).
new_size	The size of the new allocation (that get allocated).
alignment	The byte alignment to be used for the reallocation.
tag	Indicates the use of the allocated block.

Returns: If successful, a pointer to a block of allocated memory; otherwise 0.

◆ kreallocate_report()

KAPI void kreallocate_report	(	u64	old_size,
		u64	new_size,
		memory_tag	tag
	)

Reports an allocation associated with the application, but made externally. This can be done for items allocated within 3rd party libraries, for example, to track allocations but not perform them.

Parameters

old_size	The size of the old allocation.
new_size	The size of the new allocation.
tag	Indicates the use of the allocated block.

◆ kset_memory()

KAPI void* kset_memory	(	void *	dest,
		i32	value,
		u64	size
	)

Sets the bytes of memory located at dest to value over the given size.

Parameters

dest	A pointer to the destination block of memory to be set.
value	The value to be set.
size	The size in bytes to copy over to.

Returns: A pointer to the destination block of memory.

◆ kzero_memory()

KAPI void* kzero_memory	(	void *	block,
		u64	size
	)

Zeroes out the provided memory block.

Parameters

block	A pointer to the block of memory to be zeroed out.
size	The size in bytes to zero out.
A	pointer to the zeroed out block of memory.

◆ memory_system_initialize()

KAPI b8 memory_system_initialize ( memory_system_configuration config )

Initializes the memory system.

Parameters

config The configuration for this system.

◆ memory_system_shutdown()

KAPI void memory_system_shutdown ( void )

Shuts down the memory system.

◆ pack_u8_into_u32()

KAPI u32 pack_u8_into_u32	(	u8	x,
		u8	y,
		u8	z,
		u8	w
	)

Packs the values of 4 u8s into a single u32.

Parameters

x	The first u8 to pack.
y	The second u8 to pack.
z	The third u8 to pack.
w	The fourth u8 to pack.

Returns: The packed u32.

◆ unpack_u8_from_u32()

KAPI b8 unpack_u8_from_u32	(	u32	n,
		u8 *	x,
		u8 *	y,
		u8 *	z,
		u8 *	w
	)

Attempts to unpack 4 u8s from a u32.

Parameters

n	The u32 to extract from.
x	The first u8 to extract to. Required.
y	The second u8 to extract to. Required.
z	The third u8 to extract to. Required.
w	The fourth u8 to extract to. Required.

Returns: True if success, otherwise false.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ KALLOC_TYPE

◆ KALLOC_TYPE_CARRAY

◆ KCOPY_TYPE

◆ KCOPY_TYPE_CARRAY

◆ KFREE_TYPE

◆ KFREE_TYPE_CARRAY

◆ KREALLOC_TYPE_CARRAY

◆ KRESIZE_ARRAY

Typedef Documentation

◆ frame_allocator_int

◆ memory_system_configuration

◆ memory_tag

Enumeration Type Documentation

◆ memory_tag

Function Documentation

◆ get_memory_alloc_count()

◆ get_memory_usage_str()

◆ kallocate()

◆ kallocate_aligned()

◆ kallocate_report()

◆ kcopy_memory()

◆ kfree()

◆ kfree_aligned()

◆ kfree_report()

◆ kmemory_get_size_alignment()

◆ kreallocate()

◆ kreallocate_aligned()

◆ kreallocate_report()

◆ kset_memory()

◆ kzero_memory()

◆ memory_system_initialize()

◆ memory_system_shutdown()

◆ pack_u8_into_u32()

◆ unpack_u8_from_u32()