1 /** 2 * \file wasmtime/memory.hh 3 */ 4 5 #ifndef WASMTIME_MEMORY_HH 6 #define WASMTIME_MEMORY_HH 7 8 #include <wasmtime/error.hh> 9 #include <wasmtime/memory.h> 10 #include <wasmtime/span.hh> 11 #include <wasmtime/store.hh> 12 #include <wasmtime/types/memory.hh> 13 14 namespace wasmtime { 15 16 /** 17 * \brief A WebAssembly linear memory. 18 * 19 * This class represents a WebAssembly memory, either created through 20 * instantiating a module or a host memory. 21 * 22 * Note that this type does not itself own any resources. It points to resources 23 * owned within a `Store` and the `Store` must be passed in as the first 24 * argument to the functions defined on `Table`. Note that if the wrong `Store` 25 * is passed in then the process will be aborted. 26 */ 27 class Memory { 28 friend class Instance; 29 wasmtime_memory_t memory; 30 31 public: 32 /// Creates a new memory from the raw underlying C API representation. Memory(wasmtime_memory_t memory)33 Memory(wasmtime_memory_t memory) : memory(memory) {} 34 35 /// Creates a new host-defined memory with the type specified. create(Store::Context cx,const MemoryType & ty)36 static Result<Memory> create(Store::Context cx, const MemoryType &ty) { 37 wasmtime_memory_t memory; 38 auto *error = wasmtime_memory_new(cx.ptr, ty.ptr.get(), &memory); 39 if (error != nullptr) { 40 return Error(error); 41 } 42 return Memory(memory); 43 } 44 45 /// Returns the type of this memory. type(Store::Context cx) const46 MemoryType type(Store::Context cx) const { 47 return wasmtime_memory_type(cx.ptr, &memory); 48 } 49 50 /// Returns the size, in WebAssembly pages, of this memory. size(Store::Context cx) const51 uint64_t size(Store::Context cx) const { 52 return wasmtime_memory_size(cx.ptr, &memory); 53 } 54 55 /// Returns a `span` of where this memory is located in the host. 56 /// 57 /// Note that embedders need to be very careful in their usage of the returned 58 /// `span`. It can be invalidated with calls to `grow` and/or calls into 59 /// WebAssembly. data(Store::Context cx) const60 Span<uint8_t> data(Store::Context cx) const { 61 auto *base = wasmtime_memory_data(cx.ptr, &memory); 62 auto size = wasmtime_memory_data_size(cx.ptr, &memory); 63 return {base, size}; 64 } 65 66 /// Grows the memory by `delta` WebAssembly pages. 67 /// 68 /// On success returns the previous size of this memory in units of 69 /// WebAssembly pages. grow(Store::Context cx,uint64_t delta) const70 Result<uint64_t> grow(Store::Context cx, uint64_t delta) const { 71 uint64_t prev = 0; 72 auto *error = wasmtime_memory_grow(cx.ptr, &memory, delta, &prev); 73 if (error != nullptr) { 74 return Error(error); 75 } 76 return prev; 77 } 78 79 /// Returns the size of a page, in bytes, for this memory. 80 /// 81 /// WebAssembly memories are made up of a whole number of pages, so the byte 82 /// size will always be a multiple of their page size. Different Wasm memories 83 /// may have different page sizes. 84 /// 85 /// By default this is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or `65536`) 86 /// but [the custom-page-sizes proposal] allows opting into a page size of 87 /// `1`. Future extensions might allow any power of two as a page size. 88 /// 89 /// [the custom-page-sizes proposal]: 90 /// https://github.com/WebAssembly/custom-page-sizes page_size(Store::Context cx) const91 uint64_t page_size(Store::Context cx) const { 92 return wasmtime_memory_page_size(cx.ptr, &memory); 93 } 94 95 /// Returns the log2 of this memory's page size, in bytes. 96 /// 97 /// WebAssembly memories are made up of a whole number of pages, so the byte 98 /// size will always be a multiple of their page size. Different Wasm memories 99 /// may have different page sizes. 100 /// 101 /// By default the page size is 64KiB (aka `0x10000`, `2**16`, `1<<16`, or 102 /// `65536`) but [the custom-page-sizes proposal] allows opting into a page 103 /// size of `1`. Future extensions might allow any power of two as a page 104 /// size. 105 /// 106 /// [the custom-page-sizes proposal]: 107 /// https://github.com/WebAssembly/custom-page-sizes page_size_log2(Store::Context cx) const108 uint8_t page_size_log2(Store::Context cx) const { 109 return wasmtime_memory_page_size_log2(cx.ptr, &memory); 110 } 111 112 /// Returns the raw underlying C API memory this is using. capi() const113 const wasmtime_memory_t &capi() const { return memory; } 114 }; 115 116 } // namespace wasmtime 117 118 #endif // WASMTIME_MEMORY_HH 119