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