1 /**
2  * \file wasmtime/sharedmemory.h
3  *
4  * Wasmtime API for interacting with wasm shared memories.
5  */
6 
7 #ifndef WASMTIME_SHAREDMEMORY_H
8 #define WASMTIME_SHAREDMEMORY_H
9 
10 #include <wasm.h>
11 #include <wasmtime/error.h>
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /**
18  * \brief Interface for shared memories.
19  *
20  * For more information see the Rust documentation at:
21  * https://docs.wasmtime.dev/api/wasmtime/struct.SharedMemory.html
22  */
23 typedef struct wasmtime_sharedmemory wasmtime_sharedmemory_t;
24 
25 /**
26  * \brief Creates a new WebAssembly shared linear memory
27  *
28  * \param engine engine that created shared memory is associated with
29  * \param ty the type of the memory to create
30  * \param ret where to store the returned memory
31  *
32  * If an error happens when creating the memory it's returned and owned by the
33  * caller. If an error happens then `ret` is not filled in.
34  */
35 WASM_API_EXTERN wasmtime_error_t *
36 wasmtime_sharedmemory_new(const wasm_engine_t *engine,
37                           const wasm_memorytype_t *ty,
38                           wasmtime_sharedmemory_t **ret);
39 
40 /**
41  * \brief Deletes shared linear memory
42  *
43  * \param memory memory to be deleted
44  */
45 WASM_API_EXTERN void
46 wasmtime_sharedmemory_delete(wasmtime_sharedmemory_t *memory);
47 
48 /**
49  * \brief Clones shared linear memory
50  *
51  * \param memory memory to be cloned
52  *
53  * This function makes shallow clone, ie. copy of reference counted
54  * memory handle.
55  */
56 WASM_API_EXTERN wasmtime_sharedmemory_t *
57 wasmtime_sharedmemory_clone(const wasmtime_sharedmemory_t *memory);
58 
59 /**
60  * \brief Moves shared linear memory into wasmtime_extern_t object
61  *
62  * \param memory memory to be moved
63  * \param out where to store resulting `wasmtime_extern_t`
64  *
65  * This function moves ownership of `memory` into resulting `wasmtime_extern_t`.
66  */
67 WASM_API_EXTERN void
68 wasmtime_sharedmemory_into_extern(wasmtime_sharedmemory_t *memory,
69                                   wasmtime_extern_t *out);
70 
71 /**
72  * \brief Returns the type of the shared memory specified
73  */
74 WASM_API_EXTERN wasm_memorytype_t *
75 wasmtime_sharedmemory_type(const wasmtime_sharedmemory_t *memory);
76 
77 /**
78  * \brief Returns the base pointer in memory where
79           the shared linear memory starts.
80  */
81 WASM_API_EXTERN uint8_t *
82 wasmtime_sharedmemory_data(const wasmtime_sharedmemory_t *memory);
83 
84 /**
85  * \brief Returns the byte length of this shared linear memory.
86  */
87 WASM_API_EXTERN size_t
88 wasmtime_sharedmemory_data_size(const wasmtime_sharedmemory_t *memory);
89 
90 /**
91  * \brief Returns the length, in WebAssembly pages, of this shared linear memory
92  */
93 WASM_API_EXTERN uint64_t
94 wasmtime_sharedmemory_size(const wasmtime_sharedmemory_t *memory);
95 
96 /**
97  * \brief Attempts to grow the specified shared memory by `delta` pages.
98  *
99  * \param memory the memory to grow
100  * \param delta the number of pages to grow by
101  * \param prev_size where to store the previous size of memory
102  *
103  * If memory cannot be grown then `prev_size` is left unchanged and an error is
104  * returned. Otherwise `prev_size` is set to the previous size of the memory, in
105  * WebAssembly pages, and `NULL` is returned.
106  */
107 WASM_API_EXTERN wasmtime_error_t *
108 wasmtime_sharedmemory_grow(const wasmtime_sharedmemory_t *memory,
109                            uint64_t delta, uint64_t *prev_size);
110 
111 #ifdef __cplusplus
112 } // extern "C"
113 #endif
114 
115 #endif // WASMTIME_SHAREDMEMORY_H
116