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