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 Returns the type of the shared memory specified
61  */
62 WASM_API_EXTERN wasm_memorytype_t *
63 wasmtime_sharedmemory_type(const wasmtime_sharedmemory_t *memory);
64 
65 /**
66  * \brief Returns the base pointer in memory where
67           the shared linear memory starts.
68  */
69 WASM_API_EXTERN uint8_t *
70 wasmtime_sharedmemory_data(const wasmtime_sharedmemory_t *memory);
71 
72 /**
73  * \brief Returns the byte length of this shared linear memory.
74  */
75 WASM_API_EXTERN size_t
76 wasmtime_sharedmemory_data_size(const wasmtime_sharedmemory_t *memory);
77 
78 /**
79  * \brief Returns the length, in WebAssembly pages, of this shared linear memory
80  */
81 WASM_API_EXTERN uint64_t
82 wasmtime_sharedmemory_size(const wasmtime_sharedmemory_t *memory);
83 
84 /**
85  * \brief Attempts to grow the specified shared memory by `delta` pages.
86  *
87  * \param memory the memory to grow
88  * \param delta the number of pages to grow by
89  * \param prev_size where to store the previous size of memory
90  *
91  * If memory cannot be grown then `prev_size` is left unchanged and an error is
92  * returned. Otherwise `prev_size` is set to the previous size of the memory, in
93  * WebAssembly pages, and `NULL` is returned.
94  */
95 WASM_API_EXTERN wasmtime_error_t *
96 wasmtime_sharedmemory_grow(const wasmtime_sharedmemory_t *memory,
97                            uint64_t delta, uint64_t *prev_size);
98 
99 #ifdef __cplusplus
100 } // extern "C"
101 #endif
102 
103 #endif // WASMTIME_SHAREDMEMORY_H
104