wasmtime/runtime/component/mod.rs
1//! # Embedding API for the Component Model
2//!
3//! This module contains the embedding API for the [Component Model] in
4//! Wasmtime. This module requires the `component-model` feature to be enabled,
5//! which is enabled by default. The embedding API here is mirrored after the
6//! core wasm embedding API at the crate root and is intended to have the same
7//! look-and-feel while handling concepts of the component model.
8//!
9//! [Component Model]: https://component-model.bytecodealliance.org
10//!
11//! The component model is a broad topic which can't be explained here fully, so
12//! it's recommended to read over individual items' documentation to see more
13//! about the capabilities of the embedding API. At a high-level, however,
14//! perhaps the most interesting items in this module are:
15//!
16//! * [`Component`] - a compiled component ready to be instantiated. Similar to
17//! a [`Module`](crate::Module) for core wasm.
18//!
19//! * [`Linker`] - a component-style location for defining host functions. This
20//! is not the same as [`wasmtime::Linker`](crate::Linker) for core wasm
21//! modules.
22//!
23//! * [`bindgen!`] - a macro to generate Rust bindings for a [WIT] [world]. This
24//! maps all WIT types into Rust automatically and generates traits for
25//! embedders to implement.
26//!
27//! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
28//! [world]: https://component-model.bytecodealliance.org/design/worlds.html
29//!
30//! Embedders of the component model will typically start by defining their API
31//! in [WIT]. This describes what will be available to guests and what needs to
32//! be provided to the embedder by the guest. This [`world`][world] that was
33//! created is then fed into [`bindgen!`] to generate types and traits for the
34//! embedder to use. The embedder then implements these traits, adds
35//! functionality via the generated `add_to_linker` method (see [`bindgen!`] for
36//! more info), and then instantiates/executes a component.
37//!
38//! It's recommended to read over the [documentation for the Component
39//! Model][Component Model] to get an overview about how to build components
40//! from various languages.
41//!
42//! ## Example Usage
43//!
44//! Imagine you have the following WIT package definition in a file called world.wit
45//! along with a component (my_component.wasm) that targets `my-world`:
46//!
47//! ```text,ignore
48//! package component:my-package;
49//!
50//! world my-world {
51//! import name: func() -> string;
52//! export greet: func() -> string;
53//! }
54//! ```
55//!
56//! You can instantiate and call the component like so:
57//!
58//! ```
59//! fn main() -> wasmtime::Result<()> {
60//! # if true { return Ok(()) }
61//! // Instantiate the engine and store
62//! let engine = wasmtime::Engine::default();
63//! let mut store = wasmtime::Store::new(&engine, ());
64//!
65//! // Load the component from disk
66//! let bytes = std::fs::read("my_component.wasm")?;
67//! let component = wasmtime::component::Component::new(&engine, bytes)?;
68//!
69//! // Configure the linker
70//! let mut linker = wasmtime::component::Linker::new(&engine);
71//! // The component expects one import `name` that
72//! // takes no params and returns a string
73//! linker
74//! .root()
75//! .func_wrap("name", |_store, _params: ()| {
76//! Ok((String::from("Alice"),))
77//! })?;
78//!
79//! // Instantiate the component
80//! let instance = linker.instantiate(&mut store, &component)?;
81//!
82//! // Call the `greet` function
83//! let func = instance.get_func(&mut store, "greet").expect("greet export not found");
84//! let mut result = [wasmtime::component::Val::String("".into())];
85//! func.call(&mut store, &[], &mut result)?;
86//!
87//! // This should print out `Greeting: [String("Hello, Alice!")]`
88//! println!("Greeting: {:?}", result);
89//!
90//! Ok(())
91//! }
92//! ```
93//!
94//! Manually configuring the linker and calling untyped component exports is
95//! a bit tedious and error prone. The [`bindgen!`] macro can be used to
96//! generate bindings eliminating much of this boilerplate.
97//!
98//! See the docs for [`bindgen!`] for more information on how to use it.
99
100#![allow(
101 rustdoc::redundant_explicit_links,
102 reason = "rustdoc appears to lie about a warning above, so squelch it for now"
103)]
104
105mod component;
106#[cfg(feature = "component-model-async")]
107pub(crate) mod concurrent;
108mod func;
109mod has_data;
110mod instance;
111mod linker;
112mod matching;
113mod resource_table;
114mod resources;
115mod storage;
116pub(crate) mod store;
117pub mod types;
118mod values;
119pub use self::component::{Component, ComponentExportIndex};
120#[cfg(feature = "component-model-async")]
121pub use self::concurrent::{
122 AbortHandle, Access, Accessor, AccessorTask, AsAccessor, ErrorContext, FutureReader,
123 FutureWriter, GuardedFutureReader, GuardedFutureWriter, GuardedStreamReader,
124 GuardedStreamWriter, ReadBuffer, StreamReader, StreamWriter, VMComponentAsyncStore, VecBuffer,
125 WriteBuffer,
126};
127pub use self::func::{
128 ComponentNamedList, ComponentType, Func, Lift, Lower, TypedFunc, WasmList, WasmStr,
129};
130pub use self::has_data::*;
131pub use self::instance::{Instance, InstanceExportLookup, InstancePre};
132pub use self::linker::{Linker, LinkerInstance};
133pub use self::resource_table::{ResourceTable, ResourceTableError};
134pub use self::resources::{Resource, ResourceAny};
135pub use self::types::{ResourceType, Type};
136pub use self::values::Val;
137
138pub(crate) use self::instance::RuntimeImport;
139pub(crate) use self::resources::HostResourceData;
140pub(crate) use self::store::ComponentInstanceId;
141
142// Re-export wasm_wave crate so the compatible version of this dep doesn't have to be
143// tracked separately from wasmtime.
144#[cfg(feature = "wave")]
145pub use wasm_wave;
146
147// These items are used by `#[derive(ComponentType, Lift, Lower)]`, but they are not part of
148// Wasmtime's API stability guarantees
149#[doc(hidden)]
150pub mod __internal {
151 pub use super::func::{
152 ComponentVariant, LiftContext, LowerContext, Options, bad_type_info, format_flags,
153 lower_payload, typecheck_enum, typecheck_flags, typecheck_record, typecheck_variant,
154 };
155 pub use super::matching::InstanceType;
156 pub use crate::MaybeUninitExt;
157 pub use crate::map_maybe_uninit;
158 pub use crate::store::StoreOpaque;
159 pub use alloc::boxed::Box;
160 pub use alloc::string::String;
161 pub use alloc::vec::Vec;
162 pub use anyhow;
163 pub use core::cell::RefCell;
164 pub use core::future::Future;
165 pub use core::mem::transmute;
166 pub use wasmtime_environ;
167 pub use wasmtime_environ::component::{CanonicalAbiInfo, ComponentTypes, InterfaceType};
168}
169
170pub(crate) use self::store::ComponentStoreData;
171
172/// Generate bindings for a [WIT world].
173///
174/// [WIT world]: https://component-model.bytecodealliance.org/design/worlds.html
175/// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
176///
177/// This macro ingests a [WIT world] and will generate all the necessary
178/// bindings for instantiating components that ascribe to the `world`. This
179/// provides a higher-level representation of working with a component than the
180/// raw [`Instance`] type which must be manually-type-checked and manually have
181/// its imports provided via the [`Linker`] type.
182///
183/// # Examples
184///
185/// Examples for this macro can be found in the [`bindgen_examples`] module
186/// documentation. That module has a submodule-per-example which includes the
187/// source code, with WIT, used to generate the structures along with the
188/// generated code itself in documentation.
189///
190/// # Debugging and Exploring
191///
192/// If you need to debug the output of `bindgen!` you can try using the
193/// `WASMTIME_DEBUG_BINDGEN=1` environment variable. This will write the
194/// generated code to a file on disk so rustc can produce better error messages
195/// against the actual generated source instead of the macro invocation itself.
196/// This additionally can enable opening up the generated code in an editor and
197/// exploring it (through an error message).
198///
199/// The generated bindings can additionally be explored with `cargo doc` to see
200/// what's generated. It's also recommended to browse the [`bindgen_examples`]
201/// for example generated structures and example generated code.
202///
203/// # Syntax
204///
205/// This procedural macro accepts a few different syntaxes. The primary purpose
206/// of this macro is to locate a WIT package, parse it, and then extract a
207/// `world` from the parsed package. There are then codegen-specific options to
208/// the bindings themselves which can additionally be specified.
209///
210/// Usage of this macro looks like:
211///
212/// ```rust
213/// # macro_rules! bindgen { ($($t:tt)*) => () }
214/// // Parse the `wit/` folder adjacent to this crate's `Cargo.toml` and look
215/// // for a single `world` in it. There must be exactly one for this to
216/// // succeed.
217/// bindgen!();
218///
219/// // Parse the `wit/` folder adjacent to this crate's `Cargo.toml` and look
220/// // for the world `foo` contained in it.
221/// bindgen!("foo");
222///
223/// // Parse the folder `other/wit/folder` adjacent to `Cargo.toml`.
224/// bindgen!(in "other/wit/folder");
225/// bindgen!("foo" in "other/wit/folder");
226///
227/// // Parse the file `foo.wit` as a single-file WIT package with no
228/// // dependencies.
229/// bindgen!("foo" in "foo.wit");
230///
231/// // Specify a suite of options to the bindings generation, documented below
232/// bindgen!({
233/// world: "foo",
234/// path: "other/path/to/wit",
235/// // ...
236/// });
237/// ```
238///
239/// # Options Reference
240///
241/// This is an example listing of all options that this macro supports along
242/// with documentation for each option and example syntax for each option.
243///
244/// ```rust
245/// # macro_rules! bindgen { ($($t:tt)*) => () }
246/// bindgen!({
247/// world: "foo", // not needed if `path` has one `world`
248///
249/// // same as in `bindgen!(in "other/wit/folder")
250/// path: "other/wit/folder",
251///
252/// // Instead of `path` the WIT document can be provided inline if
253/// // desired.
254/// inline: "
255/// package my:inline;
256///
257/// world foo {
258/// // ...
259/// }
260/// ",
261///
262/// // Further configuration of imported functions. This can be used to add
263/// // functionality per-function or by default for all imports. Note that
264/// // exports are also supported via the `exports` key below.
265/// //
266/// // Functions in this list are specified as their interface first then
267/// // the raw wasm name of the function. Interface versions can be
268/// // optionally omitted and prefixes are also supported to configure
269/// // entire interfaces at once for example. Only the first matching item
270/// // in this list is used to configure a function.
271/// //
272/// // Configuration for a function is a set of flags which can be added
273/// // per-function. Each flag's meaning is documented below and the final
274/// // set of flags for a function are calculated by the first matching
275/// // rule below unioned with the default flags inferred from the WIT
276/// // signature itself (unless below configures the `ignore_wit` flag).
277/// //
278/// // Specifically the defaults for a normal WIT function are empty,
279/// // meaning all flags below are disabled. For a WIT `async` function the
280/// // `async | store` flags are enabled by default, but all others are
281/// // still disabled.
282/// //
283/// // Note that unused keys in this map are a compile-time error. All
284/// // keys are required to be used and consulted.
285/// imports: {
286/// // The `async` flag is used to indicate that a Rust-level `async`
287/// // function is used on the host. This means that the host is allowed
288/// // to do async I/O. Note though that to WebAssembly itself the
289/// // function will still be blocking. This requires
290/// // `Config::async_support` to be `true` as well.
291/// "wasi:io/poll/poll": async,
292///
293/// // The `store` flag means that the host function will have access
294/// // to the store during its execution. By default host functions take
295/// // `&mut self` which only has access to the data in question
296/// // implementing the generated traits from `bindgen!`. This
297/// // configuration means that in addition to `Self` the entire store
298/// // will be accessible if necessary.
299/// //
300/// // Functions that have access to a `store` are generated in a
301/// // `HostWithStore` trait. Functions without a `store` are generated
302/// // in a `Host` trait.
303/// //
304/// // > Note: this is not yet implemented for non-async functions. This
305/// // > will result in bindgen errors right now and is intended to be
306/// // > implemented in the near future.
307/// "wasi:clocks/monotonic-clock/now": store,
308///
309/// // This is an example of combining flags where the `async` and
310/// // `store` flags are combined. This means that the generated
311/// // host function is both `async` and additionally has access to
312/// // the `store`. Note though that this configuration is not necessary
313/// // as the WIT function is itself already marked as `async`. That
314/// // means that this is the default already applied meaning that
315/// // specifying it here would be redundant.
316/// //
317/// // "wasi:clocks/monotonic-clock/[async]wait-until": async | store,
318///
319/// // The `tracing` flag indicates that `tracing!` will be used to log
320/// // entries and exits into this host API. This can assist with
321/// // debugging or just generally be used to provide logs for the host.
322/// //
323/// // By default values are traced unless they contain lists, but
324/// // tracing of lists can be enabled with `verbose_tracing` below.
325/// "my:local/api/foo": tracing,
326///
327/// // The `verbose_tracing` flag indicates that when combined with
328/// // `tracing` the values of parameters/results are added to logs.
329/// // This may include lists which may be very large.
330/// "my:local/api/other-function": tracing | verbose_tracing,
331///
332/// // The `trappable` flag indicates that this import is allowed to
333/// // generate a trap.
334/// //
335/// // Imports that may trap have their return types wrapped in
336/// // `wasmtime::Result<T>` where the `Err` variant indicates that a
337/// // trap will be raised in the guest.
338/// //
339/// // By default imports cannot trap and the return value is the return
340/// // value from the WIT bindings itself.
341/// //
342/// // Note that the `trappable` configuration can be combined with the
343/// // `trappable_error_type` configuration below to avoid having a
344/// // host function return `wasmtime::Result<Result<WitOk, WitErr>>`
345/// // for example and instead return `Result<WitOk, RustErrorType>`.
346/// "my:local/api/fallible": trappable,
347///
348/// // The `ignore_wit` flag discards the WIT-level defaults of a
349/// // function. For example this `async` WIT function will be ignored
350/// // and a synchronous function will be generated on the host.
351/// "my:local/api/[async]wait": ignore_wit,
352///
353/// // The `exact` flag ensures that the filter, here "f", only matches
354/// // functions exactly. For example "f" here would only refer to
355/// // `import f: func()` in a world. Without this flag then "f"
356/// // would also configure any package `f:*/*/*` for example.
357/// "f": exact,
358///
359/// // This is used to configure the defaults of all functions if no
360/// // other key above matches a function. Note that if specific
361/// // functions mentioned above want these flags too then the flags
362/// // must be added there too because only one matching rule in this
363/// // map is used per-function.
364/// default: async | trappable,
365/// },
366///
367/// // Same as `imports` above, but applies to exported functions.
368/// exports: { /* ... */ },
369///
370/// // This can be used to translate WIT return values of the form
371/// // `result<T, error-type>` into `Result<T, RustErrorType>` in Rust.
372/// // Users must define `RustErrorType` and the `Host` trait for the
373/// // interface which defines `error-type` will have a method
374/// // called `convert_error_type` which converts `RustErrorType`
375/// // into `wasmtime::Result<ErrorType>`. This conversion can either
376/// // return the raw WIT error (`ErrorType` here) or a trap.
377/// //
378/// // By default this option is not specified. This option only takes
379/// // effect when `trappable_imports` is set for some imports.
380/// trappable_error_type: {
381/// "wasi:io/streams/stream-error" => RustErrorType,
382/// },
383///
384/// // All generated bindgen types are "owned" meaning types like `String`
385/// // are used instead of `&str`, for example. This is the default and
386/// // ensures that the same type used in both imports and exports uses the
387/// // same generated type.
388/// ownership: Owning,
389///
390/// // Alternative to `Owning` above where borrowed types attempt to be used
391/// // instead. The `duplicate_if_necessary` configures whether duplicate
392/// // Rust types will be generated for the same WIT type if necessary, for
393/// // example when a type is used both as an import and an export.
394/// ownership: Borrowing {
395/// duplicate_if_necessary: true
396/// },
397///
398/// // Restrict the code generated to what's needed for the interface
399/// // imports in the inlined WIT document fragment.
400/// interfaces: "
401/// import wasi:cli/command;
402/// ",
403///
404/// // Remap imported interfaces or resources to types defined in Rust
405/// // elsewhere. Using this option will prevent any code from being
406/// // generated for interfaces mentioned here. Resources named here will
407/// // not have a type generated to represent the resource.
408/// //
409/// // Interfaces mapped with this option should be previously generated
410/// // with an invocation of this macro. Resources need to be mapped to a
411/// // Rust type name.
412/// with: {
413/// // This can be used to indicate that entire interfaces have
414/// // bindings generated elsewhere with a path pointing to the
415/// // bindinges-generated module.
416/// "wasi:random/random": wasmtime_wasi::p2::bindings::random::random,
417///
418/// // Similarly entire packages can also be specified.
419/// "wasi:cli": wasmtime_wasi::p2::bindings::cli,
420///
421/// // Or, if applicable, entire namespaces can additionally be mapped.
422/// "wasi": wasmtime_wasi::p2::bindings,
423///
424/// // Versions are supported if multiple versions are in play:
425/// "wasi:http/types@0.2.0": wasmtime_wasi_http::bindings::http::types,
426/// "wasi:http@0.2.0": wasmtime_wasi_http::bindings::http,
427///
428/// // The `with` key can also be used to specify the `T` used in
429/// // import bindings of `Resource<T>`. This can be done to configure
430/// // which typed resource shows up in generated bindings and can be
431/// // useful when working with the typed methods of `ResourceTable`.
432/// "wasi:filesystem/types/descriptor": MyDescriptorType,
433/// },
434///
435/// // Additional derive attributes to include on generated types (structs or enums).
436/// //
437/// // These are deduplicated and attached in a deterministic order.
438/// additional_derives: [
439/// Hash,
440/// serde::Deserialize,
441/// serde::Serialize,
442/// ],
443///
444/// // An niche configuration option to require that the `T` in `Store<T>`
445/// // is always `Send` in the generated bindings. Typically not needed
446/// // but if synchronous bindings depend on asynchronous bindings using
447/// // the `with` key then this may be required.
448/// require_store_data_send: false,
449///
450/// // If the `wasmtime` crate is depended on at a nonstandard location
451/// // or is renamed then this is the path to the root of the `wasmtime`
452/// // crate. Much of the generated code needs to refer to `wasmtime` so
453/// // this should be used if the `wasmtime` name is not wasmtime itself.
454/// //
455/// // By default this is `wasmtime`.
456/// wasmtime_crate: path::to::wasmtime,
457///
458/// // This is an in-source alternative to using `WASMTIME_DEBUG_BINDGEN`.
459/// //
460/// // Note that if this option is specified then the compiler will always
461/// // recompile your bindings. Cargo records the start time of when rustc
462/// // is spawned by this will write a file during compilation. To Cargo
463/// // that looks like a file was modified after `rustc` was spawned,
464/// // so Cargo will always think your project is "dirty" and thus always
465/// // recompile it. Recompiling will then overwrite the file again,
466/// // starting the cycle anew. This is only recommended for debugging.
467/// //
468/// // This option defaults to false.
469/// include_generated_code_from_file: false,
470/// });
471/// ```
472pub use wasmtime_component_macro::bindgen;
473
474/// Derive macro to generate implementations of the [`ComponentType`] trait.
475///
476/// This derive macro can be applied to `struct` and `enum` definitions and is
477/// used to bind either a `record`, `enum`, or `variant` in the component model.
478///
479/// Note you might be looking for [`bindgen!`] rather than this macro as that
480/// will generate the entire type for you rather than just a trait
481/// implementation.
482///
483/// This macro supports a `#[component]` attribute which is used to customize
484/// how the type is bound to the component model. A top-level `#[component]`
485/// attribute is required to specify either `record`, `enum`, or `variant`.
486///
487/// ## Records
488///
489/// `record`s in the component model correspond to `struct`s in Rust. An example
490/// is:
491///
492/// ```rust
493/// use wasmtime::component::ComponentType;
494///
495/// #[derive(ComponentType)]
496/// #[component(record)]
497/// struct Color {
498/// r: u8,
499/// g: u8,
500/// b: u8,
501/// }
502/// ```
503///
504/// which corresponds to the WIT type:
505///
506/// ```wit
507/// record color {
508/// r: u8,
509/// g: u8,
510/// b: u8,
511/// }
512/// ```
513///
514/// Note that the name `Color` here does not need to match the name in WIT.
515/// That's purely used as a name in Rust of what to refer to. The field names
516/// must match that in WIT, however. Field names can be customized with the
517/// `#[component]` attribute though.
518///
519/// ```rust
520/// use wasmtime::component::ComponentType;
521///
522/// #[derive(ComponentType)]
523/// #[component(record)]
524/// struct VerboseColor {
525/// #[component(name = "r")]
526/// red: u8,
527/// #[component(name = "g")]
528/// green: u8,
529/// #[component(name = "b")]
530/// blue: u8,
531/// }
532/// ```
533///
534/// Also note that field ordering is significant at this time and must match
535/// WIT.
536///
537/// ## Variants
538///
539/// `variant`s in the component model correspond to a subset of shapes of a Rust
540/// `enum`. Variants in the component model have a single optional payload type
541/// which means that not all Rust `enum`s correspond to component model
542/// `variant`s. An example variant is:
543///
544/// ```rust
545/// use wasmtime::component::ComponentType;
546///
547/// #[derive(ComponentType)]
548/// #[component(variant)]
549/// enum Filter {
550/// #[component(name = "none")]
551/// None,
552/// #[component(name = "all")]
553/// All,
554/// #[component(name = "some")]
555/// Some(Vec<String>),
556/// }
557/// ```
558///
559/// which corresponds to the WIT type:
560///
561/// ```wit
562/// variant filter {
563/// none,
564/// all,
565/// some(list<string>),
566/// }
567/// ```
568///
569/// The `variant` style of derive allows an optional payload on Rust `enum`
570/// variants but it must be a single unnamed field. Variants of the form `Foo(T,
571/// U)` or `Foo { name: T }` are not supported at this time.
572///
573/// Note that the order of variants in Rust must match the order of variants in
574/// WIT. Additionally it's likely that `#[component(name = "...")]` is required
575/// on all Rust `enum` variants because the name currently defaults to the Rust
576/// name which is typically UpperCamelCase whereas WIT uses kebab-case.
577///
578/// ## Enums
579///
580/// `enum`s in the component model correspond to C-like `enum`s in Rust. Note
581/// that a component model `enum` does not allow any payloads so the Rust `enum`
582/// must additionally have no payloads.
583///
584/// ```rust
585/// use wasmtime::component::ComponentType;
586///
587/// #[derive(ComponentType)]
588/// #[component(enum)]
589/// #[repr(u8)]
590/// enum Setting {
591/// #[component(name = "yes")]
592/// Yes,
593/// #[component(name = "no")]
594/// No,
595/// #[component(name = "auto")]
596/// Auto,
597/// }
598/// ```
599///
600/// which corresponds to the WIT type:
601///
602/// ```wit
603/// enum setting {
604/// yes,
605/// no,
606/// auto,
607/// }
608/// ```
609///
610/// Note that the order of variants in Rust must match the order of variants in
611/// WIT. Additionally it's likely that `#[component(name = "...")]` is required
612/// on all Rust `enum` variants because the name currently defaults to the Rust
613/// name which is typically UpperCamelCase whereas WIT uses kebab-case.
614pub use wasmtime_component_macro::ComponentType;
615
616/// A derive macro for generating implementations of the [`Lift`] trait.
617///
618/// This macro will likely be applied in conjunction with the
619/// [`#[derive(ComponentType)]`](macro@ComponentType) macro along the lines
620/// of `#[derive(ComponentType, Lift)]`. This trait enables reading values from
621/// WebAssembly.
622///
623/// Note you might be looking for [`bindgen!`] rather than this macro as that
624/// will generate the entire type for you rather than just a trait
625/// implementation.
626///
627/// At this time this derive macro has no configuration.
628///
629/// ## Examples
630///
631/// ```rust
632/// use wasmtime::component::{ComponentType, Lift};
633///
634/// #[derive(ComponentType, Lift)]
635/// #[component(record)]
636/// struct Color {
637/// r: u8,
638/// g: u8,
639/// b: u8,
640/// }
641/// ```
642pub use wasmtime_component_macro::Lift;
643
644/// A derive macro for generating implementations of the [`Lower`] trait.
645///
646/// This macro will likely be applied in conjunction with the
647/// [`#[derive(ComponentType)]`](macro@ComponentType) macro along the lines
648/// of `#[derive(ComponentType, Lower)]`. This trait enables passing values to
649/// WebAssembly.
650///
651/// Note you might be looking for [`bindgen!`] rather than this macro as that
652/// will generate the entire type for you rather than just a trait
653/// implementation.
654///
655/// At this time this derive macro has no configuration.
656///
657/// ## Examples
658///
659/// ```rust
660/// use wasmtime::component::{ComponentType, Lower};
661///
662/// #[derive(ComponentType, Lower)]
663/// #[component(record)]
664/// struct Color {
665/// r: u8,
666/// g: u8,
667/// b: u8,
668/// }
669/// ```
670pub use wasmtime_component_macro::Lower;
671
672/// A macro to generate a Rust type corresponding to WIT `flags`
673///
674/// This macro generates a type that implements the [`ComponentType`], [`Lift`],
675/// and [`Lower`] traits. The generated Rust type corresponds to the `flags`
676/// type in WIT.
677///
678/// Example usage of this looks like:
679///
680/// ```rust
681/// use wasmtime::component::flags;
682///
683/// flags! {
684/// Permissions {
685/// #[component(name = "read")]
686/// const READ;
687/// #[component(name = "write")]
688/// const WRITE;
689/// #[component(name = "execute")]
690/// const EXECUTE;
691/// }
692/// }
693///
694/// fn validate_permissions(permissions: &mut Permissions) {
695/// if permissions.contains(Permissions::EXECUTE | Permissions::WRITE) {
696/// panic!("cannot enable both writable and executable at the same time");
697/// }
698///
699/// if permissions.contains(Permissions::READ) {
700/// panic!("permissions must at least contain read");
701/// }
702/// }
703/// ```
704///
705/// which corresponds to the WIT type:
706///
707/// ```wit
708/// flags permissions {
709/// read,
710/// write,
711/// execute,
712/// }
713/// ```
714///
715/// This generates a structure which is similar to/inspired by the [`bitflags`
716/// crate](https://crates.io/crates/bitflags). The `Permissions` structure
717/// generated implements the [`PartialEq`], [`Eq`], [`Debug`], [`BitOr`],
718/// [`BitOrAssign`], [`BitAnd`], [`BitAndAssign`], [`BitXor`], [`BitXorAssign`],
719/// and [`Not`] traits - in addition to the Wasmtime-specific component ones
720/// [`ComponentType`], [`Lift`], and [`Lower`].
721///
722/// [`BitOr`]: std::ops::BitOr
723/// [`BitOrAssign`]: std::ops::BitOrAssign
724/// [`BitAnd`]: std::ops::BitAnd
725/// [`BitAndAssign`]: std::ops::BitAndAssign
726/// [`BitXor`]: std::ops::BitXor
727/// [`BitXorAssign`]: std::ops::BitXorAssign
728/// [`Not`]: std::ops::Not
729pub use wasmtime_component_macro::flags;
730
731#[cfg(any(docsrs, test, doctest))]
732pub mod bindgen_examples;
733
734// NB: needed for the links in the docs above to work in all `cargo doc`
735// configurations and avoid errors.
736#[cfg(not(any(docsrs, test, doctest)))]
737#[doc(hidden)]
738pub mod bindgen_examples {}
739
740#[cfg(not(feature = "component-model-async"))]
741pub(crate) mod concurrent_disabled;
742
743#[cfg(not(feature = "component-model-async"))]
744pub(crate) use concurrent_disabled as concurrent;