|
| 1 | +#pragma once |
| 2 | + |
| 3 | +#include <stddef.h> |
| 4 | + |
| 5 | +#ifdef __cplusplus |
| 6 | +extern "C" { |
| 7 | +#endif |
| 8 | + |
| 9 | +// emmalloc: A lightweight web-friendly memory allocator suitable for very small applications. |
| 10 | +// Enable the usage of emmalloc by passing the linker flag -s MALLOC=emmalloc to the application. |
| 11 | + |
| 12 | +// A debug function that dumps the whole structure of malloc internal memory blocks to console. |
| 13 | +// *extremely slow*, use for debugging allocation test cases. |
| 14 | +void emmalloc_dump_memory_regions(void); |
| 15 | + |
| 16 | +// Allocates size bytes with the given pow-2 alignment. |
| 17 | +void *memalign(size_t alignment, size_t size); |
| 18 | +void *emmalloc_memalign(size_t alignment, size_t size); |
| 19 | +void *emscripten_builtin_memalign(size_t alignment, size_t size); |
| 20 | +void *aligned_alloc(size_t alignment, size_t size); |
| 21 | + |
| 22 | +// Allocates size bytes with default alignment (8 bytes) |
| 23 | +void *malloc(size_t size); |
| 24 | +void *emmalloc_malloc(size_t size); |
| 25 | +void *emscripten_builtin_malloc(size_t size); |
| 26 | + |
| 27 | +// Returns the number of bytes that are actually allocated to the given pointer ptr. |
| 28 | +// E.g. due to alignment or size requirements, the actual size of the allocation can be |
| 29 | +// larger than what was requested. |
| 30 | +size_t malloc_usable_size(void *ptr); |
| 31 | +size_t emmalloc_usable_size(void *ptr); |
| 32 | + |
| 33 | +// Frees a memory pointer allocated with any of |
| 34 | +// emmalloc_memalign, emmalloc_malloc, |
| 35 | +void free(void *ptr); |
| 36 | +void emmalloc_free(void *ptr); |
| 37 | +void emscripten_builtin_free(void *ptr); |
| 38 | + |
| 39 | +// Performs a reallocation of the given memory pointer to a new size. If the memory region |
| 40 | +// pointed by ptr cannot be resized in place, a new memory region will be allocated, old |
| 41 | +// memory copied over, and the old memory area freed. The pointer ptr must have been |
| 42 | +// allocated with one of the emmalloc memory allocation functions (malloc, memalign, ...). |
| 43 | +// If called with size == 0, the pointer ptr is freed, and a null pointer is returned. If |
| 44 | +// called with null ptr, a new pointer is allocated. |
| 45 | +void *realloc(void *ptr, size_t size); |
| 46 | +void *emmalloc_realloc(void *ptr, size_t size); |
| 47 | + |
| 48 | +// emmalloc_realloc_try() is like realloc(), but only attempts to try to resize the existing |
| 49 | +// memory area. If resizing the existing memory area fails, then realloc_try() will return 0 |
| 50 | +// (the original memory block is not freed or modified). If resizing succeeds, previous |
| 51 | +// memory contents will be valid up to min(old length, new length) bytes. |
| 52 | +// If a null pointer is passed, no allocation is attempted but the function will return 0. |
| 53 | +// If zero size is passed, the function will behave like free(). |
| 54 | +void *emmalloc_realloc_try(void *ptr, size_t size); |
| 55 | + |
| 56 | +// emmalloc_realloc_uninitialized() is like realloc(), but old memory contents |
| 57 | +// will be undefined after reallocation. (old memory is not preserved in any case) |
| 58 | +void *emmalloc_realloc_uninitialized(void *ptr, size_t size); |
| 59 | + |
| 60 | +// Like realloc(), but allows specifying the alignment to allocate to. This function cannot |
| 61 | +// be used to change the alignment of an existing allocation, but the original pointer should |
| 62 | +// be aligned to the given alignment already. |
| 63 | +void *aligned_realloc(void *ptr, size_t alignment, size_t size); |
| 64 | +void *emmalloc_aligned_realloc(void *ptr, size_t alignment, size_t size); |
| 65 | + |
| 66 | +// emmalloc_aligned_realloc_uninitialized() is like aligned_realloc(), but old memory contents |
| 67 | +// will be undefined after reallocation. (old memory is not preserved in any case) |
| 68 | +void *emmalloc_aligned_realloc_uninitialized(void *ptr, size_t alignment, size_t size); |
| 69 | + |
| 70 | +// posix_memalign allocates memory with a given alignment, like memalign, but with a slightly |
| 71 | +// different usage signature. |
| 72 | +int posix_memalign(void **memptr, size_t alignment, size_t size); |
| 73 | +int emmalloc_posix_memalign(void **memptr, size_t alignment, size_t size); |
| 74 | + |
| 75 | +// calloc allocates memory that is initialized to zero. |
| 76 | +void *calloc(size_t num, size_t size); |
| 77 | +void *emmalloc_calloc(size_t num, size_t size); |
| 78 | + |
| 79 | +// mallinfo() returns information about current emmalloc allocation state. This function |
| 80 | +// is very slow, only good for debugging. Avoid calling it for "routine" diagnostics. |
| 81 | +struct mallinfo mallinfo(); |
| 82 | +struct mallinfo emmalloc_mallinfo(); |
| 83 | + |
| 84 | +// malloc_trim() returns unused dynamic memory back to the WebAssembly heap. Returns 1 if it |
| 85 | +// actually freed any memory, and 0 if not. Note: this function does not release memory back to |
| 86 | +// the system, but it only marks memory held by emmalloc back to unused state for other users |
| 87 | +// of sbrk() to claim. |
| 88 | +int malloc_trim(size_t pad); |
| 89 | +int emmalloc_trim(size_t pad); |
| 90 | + |
| 91 | +// Validates the consistency of the malloc heap. Returns non-zero and prints an error to console |
| 92 | +// if memory map is corrupt. Returns 0 (and does not print anything) if memory is intact. |
| 93 | +int emmalloc_validate_memory_regions(void); |
| 94 | + |
| 95 | +// Computes the size of the dynamic memory region governed by emmalloc. This represents the |
| 96 | +// amount of memory that emmalloc has sbrk()ed in for itself to manage. Use this function |
| 97 | +// for memory statistics tracking purposes. Calling this function is quite fast, practically |
| 98 | +// O(1) time. |
| 99 | +size_t emmalloc_dynamic_heap_size(void); |
| 100 | + |
| 101 | +// Computes the amount of memory currently reserved under emmalloc's governance that is free |
| 102 | +// for the application to allocate. Use this function for memory statistics tracking purposes. |
| 103 | +// Note that calling this function is very slow, as it walks through each free memory block in |
| 104 | +// linear time. |
| 105 | +size_t emmalloc_free_dynamic_memory(void); |
| 106 | + |
| 107 | +// Estimates the amount of untapped memory that emmalloc could expand its dynamic memory area |
| 108 | +// via sbrk()ing. Theoretically the maximum amount of memory that can still be malloc()ed can |
| 109 | +// be calculated via emmalloc_free_dynamic_memory() + emmalloc_unclaimed_heap_memory(). |
| 110 | +// Calling this function is very fast constant time lookup. |
| 111 | +size_t emmalloc_unclaimed_heap_memory(void); |
| 112 | + |
| 113 | +// Computes a detailed fragmentation map of available free memory. Pass in a pointer to a |
| 114 | +// 32 element long array. This function populates into each array index i the number of free |
| 115 | +// memory regions that have a size 2^i <= size < 2^(i+1), and returns the total number of |
| 116 | +// free memory regions (the sum of the array entries). This function runs very slowly, as it |
| 117 | +// iterates through all free memory blocks. |
| 118 | +size_t emmalloc_compute_free_dynamic_memory_fragmentation_map(size_t freeMemorySizeMap[32]); |
| 119 | + |
| 120 | +#ifdef __cplusplus |
| 121 | +} |
| 122 | +#endif |
0 commit comments