1 /** 2 * \file wasmtime/memory.h 3 * 4 * Wasmtime API for interacting with wasm memories. 5 */ 6 7 #ifndef WASMTIME_MEMORY_H 8 #define WASMTIME_MEMORY_H 9 10 #include <wasm.h> 11 #include <wasmtime/error.h> 12 #include <wasmtime/extern.h> 13 #include <wasmtime/store.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * \brief Creates a new memory type from the specified parameters. 21 * 22 * Note that this function is preferred over #wasm_memorytype_new for 23 * compatibility with the memory64 proposal. 24 */ 25 WASM_API_EXTERN wasmtime_error_t * 26 wasmtime_memorytype_new(uint64_t min, bool max_present, uint64_t max, 27 bool is_64, bool shared, uint8_t page_size_log2, 28 wasm_memorytype_t **ret); 29 30 /** 31 * \brief Returns the minimum size, in pages, of the specified memory type. 32 * 33 * Note that this function is preferred over #wasm_memorytype_limits for 34 * compatibility with the memory64 proposal. 35 */ 36 WASM_API_EXTERN uint64_t 37 wasmtime_memorytype_minimum(const wasm_memorytype_t *ty); 38 39 /** 40 * \brief Returns the maximum size, in pages, of the specified memory type. 41 * 42 * If this memory type doesn't have a maximum size listed then `false` is 43 * returned. Otherwise `true` is returned and the `max` pointer is filled in 44 * with the specified maximum size, in pages. 45 * 46 * Note that this function is preferred over #wasm_memorytype_limits for 47 * compatibility with the memory64 proposal. 48 */ 49 WASM_API_EXTERN bool wasmtime_memorytype_maximum(const wasm_memorytype_t *ty, 50 uint64_t *max); 51 52 /** 53 * \brief Returns whether this type of memory represents a 64-bit memory. 54 */ 55 WASM_API_EXTERN bool wasmtime_memorytype_is64(const wasm_memorytype_t *ty); 56 57 /** 58 * \brief Returns whether this type of memory represents a shared memory. 59 */ 60 WASM_API_EXTERN bool wasmtime_memorytype_isshared(const wasm_memorytype_t *ty); 61 62 /** 63 * \brief Returns the page size, in bytes, of this memory type. 64 */ 65 WASM_API_EXTERN uint64_t 66 wasmtime_memorytype_page_size(const wasm_memorytype_t *ty); 67 68 /** 69 * \brief Returns the log2 of this memory type's page size, in bytes. 70 */ 71 WASM_API_EXTERN uint8_t 72 wasmtime_memorytype_page_size_log2(const wasm_memorytype_t *ty); 73 74 /** 75 * \brief Creates a new WebAssembly linear memory 76 * 77 * \param store the store to create the memory within 78 * \param ty the type of the memory to create 79 * \param ret where to store the returned memory 80 * 81 * If an error happens when creating the memory it's returned and owned by the 82 * caller. If an error happens then `ret` is not filled in. 83 */ 84 WASM_API_EXTERN wasmtime_error_t * 85 wasmtime_memory_new(wasmtime_context_t *store, const wasm_memorytype_t *ty, 86 wasmtime_memory_t *ret); 87 88 /** 89 * \brief Returns the type of the memory specified 90 */ 91 WASM_API_EXTERN wasm_memorytype_t * 92 wasmtime_memory_type(const wasmtime_context_t *store, 93 const wasmtime_memory_t *memory); 94 95 /** 96 * \brief Returns the base pointer in memory where the linear memory starts. 97 */ 98 WASM_API_EXTERN uint8_t *wasmtime_memory_data(const wasmtime_context_t *store, 99 const wasmtime_memory_t *memory); 100 101 /** 102 * \brief Returns the byte length of this linear memory. 103 */ 104 WASM_API_EXTERN size_t wasmtime_memory_data_size( 105 const wasmtime_context_t *store, const wasmtime_memory_t *memory); 106 107 /** 108 * \brief Returns the length, in WebAssembly pages, of this linear memory 109 */ 110 WASM_API_EXTERN uint64_t wasmtime_memory_size(const wasmtime_context_t *store, 111 const wasmtime_memory_t *memory); 112 113 /** 114 * \brief Attempts to grow the specified memory by `delta` pages. 115 * 116 * \param store the store that owns `memory` 117 * \param memory the memory to grow 118 * \param delta the number of pages to grow by 119 * \param prev_size where to store the previous size of memory 120 * 121 * If memory cannot be grown then `prev_size` is left unchanged and an error is 122 * returned. Otherwise `prev_size` is set to the previous size of the memory, in 123 * WebAssembly pages, and `NULL` is returned. 124 */ 125 WASM_API_EXTERN wasmtime_error_t * 126 wasmtime_memory_grow(wasmtime_context_t *store, const wasmtime_memory_t *memory, 127 uint64_t delta, uint64_t *prev_size); 128 129 /** 130 * \brief Returns the size of a page, in bytes, for this memory. 131 * 132 * \param store the store that owns `memory` 133 * \param memory the memory to get the page size of 134 * 135 * WebAssembly memories are made up of a whole number of pages, so the byte size 136 * (as returned by #wasmtime_memory_data_size) will always be a multiple of 137 * their page size. Different Wasm memories may have different page sizes. 138 * 139 * By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`) 140 * but [the custom-page-sizes proposal] allows opting into a page size of 141 * `1`. Future extensions might allow any power of two as a page size. 142 * 143 * [the custom-page-sizes proposal]: 144 * https://github.com/WebAssembly/custom-page-sizes 145 */ 146 WASM_API_EXTERN uint64_t wasmtime_memory_page_size( 147 wasmtime_context_t *store, const wasmtime_memory_t *memory); 148 149 /** 150 * \brief Returns the log2 of this memory's page size, in bytes. 151 * 152 * \param store the store that owns `memory` 153 * \param memory the memory to get the page size of 154 * 155 * WebAssembly memories are made up of a whole number of pages, so the byte size 156 * (as returned by #wasmtime_memory_data_size) will always be a multiple of 157 * their page size. Different Wasm memories may have different page sizes. 158 * 159 * By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or 160 * `65536`) but [the custom-page-sizes proposal] allows opting into a page 161 * size of `1`. Future extensions might allow any power of two as a page 162 * size. 163 * 164 * [the custom-page-sizes proposal]: 165 * https://github.com/WebAssembly/custom-page-sizes 166 */ 167 WASM_API_EXTERN uint8_t wasmtime_memory_page_size_log2( 168 wasmtime_context_t *store, const wasmtime_memory_t *memory); 169 170 #ifdef __cplusplus 171 } // extern "C" 172 #endif 173 174 #endif // WASMTIME_MEMORY_H 175