wasmedge_types/
lib.rs

1#![doc(
2    html_logo_url = "https://github.com/cncf/artwork/blob/master/projects/wasm-edge-runtime/icon/color/wasm-edge-runtime-icon-color.png?raw=true",
3    html_favicon_url = "https://raw.githubusercontent.com/cncf/artwork/49169bdbc88a7ce3c4a722c641cc2d548bd5c340/projects/wasm-edge-runtime/icon/color/wasm-edge-runtime-icon-color.svg"
4)]
5
6//! The [wasmedge-types](https://crates.io/crates/wasmedge-types) crate defines a group of common data structures used by both [wasmedge-sdk](https://crates.io/crates/wasmedge-sdk) and [wasmedge-sys](https://crates.io/crates/wasmedge-sys) crates.
7//!
8//! See also
9//!
10//! * [WasmEdge Runtime](https://wasmedge.org/)
11
12pub mod error;
13
14/// Defines WasmEdge reference types.
15#[derive(Debug, Copy, Clone, Eq, PartialEq)]
16pub enum RefType {
17    /// Refers to the infinite union of all references to host functions, regardless of their function types.
18    FuncRef,
19
20    /// Refers to the infinite union of all references to objects and that can be passed into WebAssembly under this type.
21    ExternRef,
22}
23
24impl From<ValType> for RefType {
25    fn from(value: ValType) -> Self {
26        match value {
27            ValType::FuncRef => RefType::FuncRef,
28            ValType::ExternRef => RefType::ExternRef,
29            _ => panic!("[wasmedge-types] Invalid WasmEdge_RefType: {value:#X?}"),
30        }
31    }
32}
33
34impl From<RefType> for ValType {
35    fn from(value: RefType) -> Self {
36        match value {
37            RefType::FuncRef => ValType::FuncRef,
38            RefType::ExternRef => ValType::ExternRef,
39        }
40    }
41}
42
43/// Defines WasmEdge value types.
44#[derive(Debug, Copy, Clone, Eq, PartialEq)]
45pub enum ValType {
46    /// 32-bit integer.
47    ///
48    /// Integers are not inherently signed or unsigned, their interpretation is determined by individual operations.
49    I32,
50    /// 64-bit integer.
51    ///
52    /// Integers are not inherently signed or unsigned, their interpretation is determined by individual operations.
53    I64,
54    /// 32-bit floating-point data as defined by the [IEEE 754-2019](https://ieeexplore.ieee.org/document/8766229).
55    F32,
56    /// 64-bit floating-point data as defined by the [IEEE 754-2019](https://ieeexplore.ieee.org/document/8766229).
57    F64,
58    /// 128-bit vector of packed integer or floating-point data.
59    ///
60    /// The packed data can be interpreted as signed or unsigned integers, single or double precision floating-point
61    /// values, or a single 128 bit type. The interpretation is determined by individual operations.
62    V128,
63    /// A reference to a host function.
64    FuncRef,
65    /// A reference to object.
66    ExternRef,
67    /// A reference that unsupported by c-api.
68    UnsupportedRef,
69}
70
71/// Defines the mutability property of WasmEdge Global variables.
72///
73/// `Mutability` determines the mutability property of a WasmEdge Global variable is either mutable or immutable.
74#[derive(Debug, Copy, Clone, Eq, PartialEq)]
75pub enum Mutability {
76    /// Identifies an immutable global variable.
77    Const,
78    /// Identifies a mutable global variable.
79    Var,
80}
81impl From<u32> for Mutability {
82    fn from(value: u32) -> Self {
83        match value {
84            0 => Mutability::Const,
85            1 => Mutability::Var,
86            _ => panic!("[wasmedge-types] Invalid WasmEdge_Mutability: {value:#X}"),
87        }
88    }
89}
90impl From<Mutability> for u32 {
91    fn from(value: Mutability) -> Self {
92        match value {
93            Mutability::Const => 0,
94            Mutability::Var => 1,
95        }
96    }
97}
98impl From<i32> for Mutability {
99    fn from(value: i32) -> Self {
100        match value {
101            0 => Mutability::Const,
102            1 => Mutability::Var,
103            _ => panic!("[wasmedge-types] Invalid WasmEdge_Mutability: {value:#X}"),
104        }
105    }
106}
107impl From<Mutability> for i32 {
108    fn from(value: Mutability) -> Self {
109        match value {
110            Mutability::Const => 0,
111            Mutability::Var => 1,
112        }
113    }
114}
115
116/// Defines WasmEdge AOT compiler optimization level.
117#[derive(Clone, Copy, Debug, PartialEq, Eq)]
118pub enum CompilerOptimizationLevel {
119    /// Disable as many optimizations as possible.
120    O0,
121
122    /// Optimize quickly without destroying debuggability.
123    O1,
124
125    /// Optimize for fast execution as much as possible without triggering significant incremental compile time or code size growth.
126    O2,
127
128    ///  Optimize for fast execution as much as possible.
129    O3,
130
131    ///  Optimize for small code size as much as possible without triggering
132    ///  significant incremental compile time or execution time slowdowns.
133    Os,
134
135    /// Optimize for small code size as much as possible.
136    Oz,
137}
138impl From<u32> for CompilerOptimizationLevel {
139    fn from(val: u32) -> CompilerOptimizationLevel {
140        match val {
141            0 => CompilerOptimizationLevel::O0,
142            1 => CompilerOptimizationLevel::O1,
143            2 => CompilerOptimizationLevel::O2,
144            3 => CompilerOptimizationLevel::O3,
145            4 => CompilerOptimizationLevel::Os,
146            5 => CompilerOptimizationLevel::Oz,
147            _ => panic!("Unknown CompilerOptimizationLevel value: {val}"),
148        }
149    }
150}
151impl From<CompilerOptimizationLevel> for u32 {
152    fn from(val: CompilerOptimizationLevel) -> u32 {
153        match val {
154            CompilerOptimizationLevel::O0 => 0,
155            CompilerOptimizationLevel::O1 => 1,
156            CompilerOptimizationLevel::O2 => 2,
157            CompilerOptimizationLevel::O3 => 3,
158            CompilerOptimizationLevel::Os => 4,
159            CompilerOptimizationLevel::Oz => 5,
160        }
161    }
162}
163impl From<i32> for CompilerOptimizationLevel {
164    fn from(val: i32) -> CompilerOptimizationLevel {
165        match val {
166            0 => CompilerOptimizationLevel::O0,
167            1 => CompilerOptimizationLevel::O1,
168            2 => CompilerOptimizationLevel::O2,
169            3 => CompilerOptimizationLevel::O3,
170            4 => CompilerOptimizationLevel::Os,
171            5 => CompilerOptimizationLevel::Oz,
172            _ => panic!("Unknown CompilerOptimizationLevel value: {val}"),
173        }
174    }
175}
176impl From<CompilerOptimizationLevel> for i32 {
177    fn from(val: CompilerOptimizationLevel) -> i32 {
178        match val {
179            CompilerOptimizationLevel::O0 => 0,
180            CompilerOptimizationLevel::O1 => 1,
181            CompilerOptimizationLevel::O2 => 2,
182            CompilerOptimizationLevel::O3 => 3,
183            CompilerOptimizationLevel::Os => 4,
184            CompilerOptimizationLevel::Oz => 5,
185        }
186    }
187}
188
189/// Defines WasmEdge AOT compiler output binary format.
190#[derive(Clone, Copy, Debug, PartialEq, Eq)]
191pub enum CompilerOutputFormat {
192    /// Native dynamic library format.
193    Native,
194
195    /// WebAssembly with AOT compiled codes in custom sections.
196    Wasm,
197}
198impl From<u32> for CompilerOutputFormat {
199    fn from(val: u32) -> CompilerOutputFormat {
200        match val {
201            0 => CompilerOutputFormat::Native,
202            1 => CompilerOutputFormat::Wasm,
203            _ => panic!("Unknown CompilerOutputFormat value: {val}"),
204        }
205    }
206}
207impl From<CompilerOutputFormat> for u32 {
208    fn from(val: CompilerOutputFormat) -> u32 {
209        match val {
210            CompilerOutputFormat::Native => 0,
211            CompilerOutputFormat::Wasm => 1,
212        }
213    }
214}
215impl From<i32> for CompilerOutputFormat {
216    fn from(val: i32) -> CompilerOutputFormat {
217        match val {
218            0 => CompilerOutputFormat::Native,
219            1 => CompilerOutputFormat::Wasm,
220            _ => panic!("Unknown CompilerOutputFormat value: {val}"),
221        }
222    }
223}
224impl From<CompilerOutputFormat> for i32 {
225    fn from(val: CompilerOutputFormat) -> i32 {
226        match val {
227            CompilerOutputFormat::Native => 0,
228            CompilerOutputFormat::Wasm => 1,
229        }
230    }
231}
232
233/// Defines WasmEdge host module registration enum.
234#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
235pub enum HostRegistration {
236    Wasi,
237    WasmEdgeProcess,
238    WasiNn,
239    WasiCryptoCommon,
240    WasiCryptoAsymmetricCommon,
241    WasiCryptoKx,
242    WasiCryptoSignatures,
243    WasiCryptoSymmetric,
244}
245impl From<u32> for HostRegistration {
246    fn from(val: u32) -> Self {
247        match val {
248            0 => HostRegistration::Wasi,
249            1 => HostRegistration::WasmEdgeProcess,
250            2 => HostRegistration::WasiNn,
251            3 => HostRegistration::WasiCryptoCommon,
252            4 => HostRegistration::WasiCryptoAsymmetricCommon,
253            5 => HostRegistration::WasiCryptoKx,
254            6 => HostRegistration::WasiCryptoSignatures,
255            7 => HostRegistration::WasiCryptoSymmetric,
256            _ => panic!("Unknown WasmEdge_HostRegistration value: {val}"),
257        }
258    }
259}
260impl From<HostRegistration> for u32 {
261    fn from(val: HostRegistration) -> u32 {
262        match val {
263            HostRegistration::Wasi => 0,
264            HostRegistration::WasmEdgeProcess => 1,
265            HostRegistration::WasiNn => 2,
266            HostRegistration::WasiCryptoCommon => 3,
267            HostRegistration::WasiCryptoAsymmetricCommon => 4,
268            HostRegistration::WasiCryptoKx => 5,
269            HostRegistration::WasiCryptoSignatures => 6,
270            HostRegistration::WasiCryptoSymmetric => 7,
271        }
272    }
273}
274
275/// Defines the type of external WasmEdge instances.
276#[derive(Debug, Clone, PartialEq, Eq)]
277pub enum ExternalInstanceType {
278    /// A WasmEdge instance that is a WasmEdge Func.
279    Func(FuncType),
280    /// A WasmEdge instance that is a WasmEdge Table.
281    Table(TableType),
282    /// A WasmEdge instance that is a WasmEdge Memory.
283    Memory(MemoryType),
284    /// A WasmEdge instance that is a WasmEdge Global.
285    Global(GlobalType),
286}
287impl From<u32> for ExternalInstanceType {
288    fn from(value: u32) -> Self {
289        match value {
290            0 => ExternalInstanceType::Func(FuncType::default()),
291            1 => ExternalInstanceType::Table(TableType::default()),
292            2 => ExternalInstanceType::Memory(MemoryType::default()),
293            3 => ExternalInstanceType::Global(GlobalType::default()),
294            _ => panic!("[wasmedge-types] Invalid WasmEdge_ExternalType: {value:#X}",),
295        }
296    }
297}
298impl From<i32> for ExternalInstanceType {
299    fn from(value: i32) -> Self {
300        match value {
301            0 => ExternalInstanceType::Func(FuncType::default()),
302            1 => ExternalInstanceType::Table(TableType::default()),
303            2 => ExternalInstanceType::Memory(MemoryType::default()),
304            3 => ExternalInstanceType::Global(GlobalType::default()),
305            _ => panic!("[wasmedge-types] Invalid WasmEdge_ExternalType: {value:#X}",),
306        }
307    }
308}
309impl std::fmt::Display for ExternalInstanceType {
310    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
311        let message = match self {
312            ExternalInstanceType::Func(_) => "function",
313            ExternalInstanceType::Table(_) => "table",
314            ExternalInstanceType::Memory(_) => "memory",
315            ExternalInstanceType::Global(_) => "global",
316        };
317        write!(f, "{message}")
318    }
319}
320
321/// Struct of WasmEdge FuncType.
322///
323/// A [FuncType] is used to declare the types of the parameters and return values of a WasmEdge Func to be created.
324#[derive(Debug, Clone, PartialEq, Eq, Default)]
325pub struct FuncType {
326    args: Vec<ValType>,
327    returns: Vec<ValType>,
328}
329impl FuncType {
330    /// Creates a new [FuncType] with the given types of arguments and returns.
331    ///
332    /// # Arguments
333    ///
334    /// * `args` - A vector of [ValType]s that represent the types of the arguments.
335    ///
336    /// * `returns` - A vector of [ValType]s that represent the types of the returns.
337    pub fn new(args: Vec<ValType>, returns: Vec<ValType>) -> Self {
338        Self { args, returns }
339    }
340
341    /// Returns the types of the arguments of a host function.
342    pub fn args(&self) -> &[ValType] {
343        &self.args
344    }
345
346    /// Returns the number of the arguments of a host function.
347    pub fn args_len(&self) -> usize {
348        self.args.len()
349    }
350
351    /// Returns the types of the returns of a host function.
352    pub fn returns(&self) -> &[ValType] {
353        &self.returns
354    }
355
356    /// Returns the number of the returns of a host function.
357    pub fn returns_len(&self) -> usize {
358        self.returns.len()
359    }
360}
361
362/// Struct of WasmEdge TableType.
363///
364/// A [TableType] is used to declare the element type and the size range of a WasmEdge Table to be created.
365#[derive(Debug, Clone, PartialEq, Eq)]
366pub struct TableType {
367    elem_ty: RefType,
368    min: u32,
369    max: Option<u32>,
370}
371impl TableType {
372    /// Creates a new [TableType] with the given element type and the size range.
373    ///
374    /// # Arguments
375    ///
376    /// * `elem_ty` - The element type of the table to be created.
377    ///
378    /// * `min` - The minimum size of the table to be created.
379    ///
380    /// * `max` - The maximum size of the table to be created.    
381    pub fn new(elem_ty: RefType, min: u32, max: Option<u32>) -> Self {
382        Self { elem_ty, min, max }
383    }
384
385    /// Returns the element type defined in the [TableType].
386    pub fn elem_ty(&self) -> RefType {
387        self.elem_ty
388    }
389
390    /// Returns the minimum size defined in the [TableType].
391    pub fn minimum(&self) -> u32 {
392        self.min
393    }
394
395    /// Returns the maximum size defined in the [TableType].
396    pub fn maximum(&self) -> Option<u32> {
397        self.max
398    }
399}
400impl Default for TableType {
401    fn default() -> Self {
402        Self {
403            elem_ty: RefType::FuncRef,
404            min: 0,
405            max: None,
406        }
407    }
408}
409
410/// Struct of WasmEdge MemoryType.
411///
412/// A [MemoryType] is used to declare the size range of a WasmEdge Memory to be created.
413#[derive(Debug, Clone, PartialEq, Eq, Default)]
414pub struct MemoryType {
415    min: u32,
416    max: Option<u32>,
417    shared: bool,
418}
419impl MemoryType {
420    /// Creates a new [MemoryType] with the given size range.
421    ///
422    /// # Arguments
423    ///
424    /// * `min` - The minimum size of the memory to be created.
425    ///
426    /// * `max` - The maximum size of the memory to be created. If `shared` is set to true, `max` must be set.
427    ///
428    /// * `shared` - Enables shared memory if true.
429    pub fn new(min: u32, max: Option<u32>, shared: bool) -> WasmEdgeResult<Self> {
430        if shared && max.is_none() {
431            return Err(Box::new(error::WasmEdgeError::Mem(
432                error::MemError::CreateSharedType,
433            )));
434        }
435        Ok(Self { min, max, shared })
436    }
437
438    /// Returns the minimum size defined in the [MemoryType].
439    pub fn minimum(&self) -> u32 {
440        self.min
441    }
442
443    /// Returns the maximum size defined in the [MemoryType].
444    pub fn maximum(&self) -> Option<u32> {
445        self.max
446    }
447
448    /// Returns whether the memory is shared.
449    pub fn shared(&self) -> bool {
450        self.shared
451    }
452}
453
454/// Struct of WasmEdge GlobalType.
455///
456/// A [GlobalType] is used to declare the type of a WasmEdge Global to be created.
457#[derive(Debug, Clone, PartialEq, Eq)]
458pub struct GlobalType {
459    ty: ValType,
460    mutability: Mutability,
461}
462impl GlobalType {
463    /// Creates a new [GlobalType] with the given value type and mutability.
464    ///
465    /// # Arguments
466    ///
467    /// * `ty` - The value type of the global to be created.
468    ///
469    /// * `mutability` - The value mutability property of the global to be created.
470    pub fn new(ty: ValType, mutability: Mutability) -> Self {
471        Self { ty, mutability }
472    }
473
474    /// Returns the value type defined in the [GlobalType].
475    pub fn value_ty(&self) -> ValType {
476        self.ty
477    }
478
479    /// Returns the value mutability property defined in the [GlobalType].
480    pub fn mutability(&self) -> Mutability {
481        self.mutability
482    }
483}
484impl Default for GlobalType {
485    fn default() -> Self {
486        Self {
487            ty: ValType::I32,
488            mutability: Mutability::Var,
489        }
490    }
491}
492
493/// Parses in-memory bytes as either the [WebAssembly Text format](http://webassembly.github.io/spec/core/text/index.html), or a binary WebAssembly module.
494pub use wat::parse_bytes as wat2wasm;
495
496/// The WasmEdge result type.
497pub type WasmEdgeResult<T> = Result<T, Box<error::WasmEdgeError>>;
498
499/// This is a workaround solution to the [`never`](https://doc.rust-lang.org/std/primitive.never.html) type in Rust. It will be replaced by `!` once it is stable.
500#[derive(Debug, Clone)]
501pub enum NeverType {}
502unsafe impl Send for NeverType {}
503unsafe impl Sync for NeverType {}
wasmedge_types/lib.rs

wasmedge_types/
lib.rs
